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Avant-propos 



Rappelons en guise de preambule qu'OpenOffice.org, suite bureautique libre et gra- 
tuite, est constituee des modules habituels de traitement de texte, de tableur, de pre- 
sentation, ainsi que de modules de dessin et d'edition de formules mathematiques. 
Tournant aussi bien sous Windows et Linux que sous Mac OS X, elle peut etre uti- 
lisee en lieu et place de la suite Microsoft Office. 



A NOTER OpenOffice.org et StarOff ice 

OpenOffice.org est une base a partir de laquelle diverses variantes ont ete derivees. La plus connue est Star- 
Office, commercialisee par Sun Microsystems, dont les versions 8 et 9 sont respectivement au niveau des 
versions 2 et 3 d'OpenOffice.org. Le contenu de ce Nvre s'applique generalement a toutes ces variantes. 



A qui s'adresse ce livre ? 

Vous etes un utilisateur de la suite OpenOffice.org 2 ou 3 (ou StarOffice 8 ou 9) et 
vous connaissez bien ses nombreuses possibilites. Cependant, dans certains cas, vous 
souhaitez simplifier des manipulations repetitives. Le langage de macros Basic 
d'OpenOffice.org, integre dans la suite, peut repondre a votre besoin. II est concu 
pour etre simple d'emploi, tout en etant puissant. 

Avec ce livre, vous apprendrez a programmer la suite OpenOffice.org, par exemple 
pour aj outer une fonctionnalite personnelle declenchee par un bouton sur une barre 
d'outils ou par un raccourci. Vous pourrez meme automatiser des traitements, par 
exemple effectuer des modifications dans toute une serie de documents Writer, ou 
lire une base de donnees pour en extraire des informations et les inserer dans un 
document Writer. 
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Ce livre est-il accessible a un debutant en programmation ? Les connaissances de base de la programma- 
tion sont exposees dans les premiers chapitres. Nous avons aussi inclus des conseils et des bonnes prati- 
ques, qui vous eviteront bien des deboires. A chaque etape, nous avons choisi des exemples volontaire- 
ment simples, chacun focalise sur le point a expliquer. Evidemment, le chemin sera plus ardu et plus long 
si vous en etes a vos tout debuts : avancez tres progressivement, en ecrivant de nombreux petits pro- 
grammes pour vous approprier les concepts de base. Ne craignez pas les erreurs, el les sont source de 
connaissances. Progressivement, vos programmes s'enrichiront et deviendront toujours plus utiles, a 
votre grande satisfaction. 



Si vous avez l'experience de la programmation, la premiere partie vous semblera 
facile. Mefiez-vous cependant des analogies avec d'autres langages, car chacun a ses 
particularites. Si vous connaissez la programmation orientee objet, vous compren- 
drez plus facilement les principes de l'API OpenOffice.org, qui sera utilisee a partir 
de la troisieme partie ; mais ce n'est pas indispensable. 

Si vous etes dans un service informatique charge d'automatiser des processus utili- 
sant la suite OpenOffice.org ou StarOffice, ou de migrer des applications ecrites 
pour la suite MS-Office, cet ouvrage vous economisera de tres nombreuses heures de 
recherche et de tatonnements et accelerera la phase d'apprentissage. Comme la 
memoire humaine a ses limites, vous souhaiterez garder ce livre a portee de main. II 
est cependant probable que vous rencontrerez des besoins non decrits ici, mais la base 
de connaissances acquises vous facilitera 1' etude de l'API OpenOffice.org. Meme si 
votre projet n'emploie pas Basic, celui-ci peut vous aider a trouver plus rapidement 
comment utiliser telle ou telle fonctionnalite et en deduire le codage equivalent dans 
votre langage. 



Precaution 

Pour tirer parti de ce livre, il est recommande de bien connaTtre les possibility qu'OpenOffice.org offre au 
niveau de son interface utilisateur, dans les domaines sur lesquels vous souhaitez intervenir par macro. 
En effet, autant eviter un developpement si quelques manipulations resolvent votre probleme ou le sim- 
plifient. Savez-vous bien utiliser les styles de paragraphe, de caractere, de page ? les modeles de 
document ? la recherche generique ? le copier-coller avec ou sans formatage ? I'utilisation des bases de 
donnees ? Savez-vous ce qu'est un signet ? N'hesitez pas a lire ces excellents livres donnant toutes les 
astuces pour etre productif sous OpenOffice.org. 

(B OpenOffice.org 2.2 efficace de Sophie Gautier, Christian Hardy, Frederic Labbe, Michel Pinquier, 
editions Eyrolles 2007. 

Q OpenOffice.org 3 efficace de Sophie Gautier, Gilles Bignebat, Christian Hardy, Michel Pinquier et 
Laurent Godard, editions Eyrolles 2009. 
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Contenu de I'ouvrage 

Vous trouverez une description complete et precise du Basic OpenOffice.org, redigee 
pour etre comprehensible pour un debutant en programmation, tout en apportant 
des informations indispensables au programmeur experimente. 

Vous apprendrez comment utiliser facilement l'interface de programmation d'appli- 
cation (API) pour lire, ecrire, modifier les documents OpenOffice.org, acceder aux 
bases de donnees, et dialoguer avec l'utilisateur. L'API d'OpenOffice.org est extre- 
mement riche et parfois complexe. II nous a fallu privilegier les sujets les plus cou- 
rants et les verifier chacun par des macros. Si vous ne trouvez pas la reponse a une 
question dans cet ouvrage, c'est peut-etre qu'il s'agit d'un cas rare et particulierement 
difficile a realiser. 

L'API est une interface independante du langage de programmation. A cet egard, les 
descriptions des fonctionnalites sont valides pour divers environnements : les lan- 
gages de script integres a OpenOffice.org (Basic, Python, JavaScript, BeanShell, 
cites au chapitre 1), le pilotage par un langage externe via COM (aborde au 
chapitre 14), voire meme dans des composants developpes en Java ou C++. Un deve- 
loppeur d'applications pourra facilement transposer dans un autre langage les exem- 
ples Basic donnes dans cet ouvrage. L'annexe A decrit les principes de 1API, son uti- 
lisation par le Basic OpenOffice.org, et comment aller plus loin avec Xray et la 
documentation de 1API et les outils d'introspection (Xray et similaires). 

Notre souci a ete d'etre clair et progressif, sans trop entrer dans des considerations 
theoriques. Nous avons pour cela cree des centaines d'exemples de macros Basic, avec 
des documents specialement configures pour chaque essai. Tous les exemples ont ete 
testes, et pour la plupart retestes, sur les versions recentes. lis sont mis a votre disposi- 
tion en telechargement libre sur le site www.editions-eyrolles.com - cela vous epargnera 
l'effort de frappe et les erreurs de resaisie. Ces exemples peuvent servir de modeles pour 
creer rapidement de nouvelles macros, en quelques copier-coller. 

Prenez votre temps en lisant les explications et les exemples : chaque phrase est 
importante. Nulle pretention litteraire pour ce texte technique. N'hesitez pas a relire 
des passages que vous pensez connaitre. 

La source de documentation etant presque exclusivement en anglais, nous avons 
choisi d'aider le lecteur peu familier de cette langue en traduisant les termes impor- 
tants et en utilisant des noms de variables en francais. A l'usage, le fait d'employer 
des noms francais facilite beaucoup 1' assimilation, meme si on lit couramment 
1'anglo-americain. 
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Ce livre n'est pas une simple traduction de documents anglais, ni une collection 
d'astuces recoltees sur les forums. II est une synthese de connaissances et presente de 
facon directement utile beaucoup d'informations peu connues, mal documentees ou 
non documentees. Nous signalons notamment des anomalies de fonctionnement, 
des limitations, ou des erreurs de documentation afin de vous eviter les difficultes que 
nous avons rencontrees. 

Nous mettons aussi a votre disposition en telechargement un grand nombre de rou- 
tines utilitaires pour simplifier de nombreux codages. Leur liste est donnee a 
l'annexe B. 

L'interface utilisateur des versions successives presente inevitablement de petites 
modifications par rapport a notre version de travail. De plus, la forme des icones peut 
varier d'une distribution a l'autre, selon le systeme d'exploitation, ou la configuration 
choisie par l'utilisateur. Cela ne devrait pas vous empecher de retrouver l'equivalent 
de ce qui est imprime dans ce livre. 

La premiere partie montre l'utilite de la programmation OpenOffice.org, et presente 
les langages de script et les diverses manieres de declencher un script. Vous verrez 
comment utiliser l'enregistreur de macro, et pourquoi il est finalement assez limite. 
Contrairement a la concurrence, OpenOffice.org supporte plusieurs langages de 
script ; nous en faisons une comparaison. Le but de la programmation Open- 
Office.org est souvent d'ajouter des fonctionnalites. Les extensions sont un moyen 
de les diffuser facilement, nous en montrerons les possibilites ainsi que les outils pour 
les produire. 

Dans la deuxieme partie, nous decrivons le langage OOoBasic. Vous faites connais- 
sance avec l'environnement de developpement integre, et vous l'utilisez pour ecrire et 
executer votre premiere macro. Vous apprenez les diverses manieres d'executer une 
macro. Meme si vous connaissez deja un Basic (par exemple Visual Basic™ qui lui 
est proche), parcourez les chapitres de cette partie. En cas de probleme d'execution, 
relisez-la, elle contient bien des details importants et souvent non decrits dans la 
documentation officielle. 

A partir de la troisieme partie, vous apprenez a ecrire ou modifier des documents 
OpenOffice.org : Writer, Calc, Draw, etc. Vous aurez besoin d'utiliser l'API, cceur 
de la programmation OpenOffice.org dans quelque langage que ce soit. Mais nous 
eviterons les exposes theoriques rebarbatifs pour nous concentrer sur les solutions a 
des besoins reels. OpenOffice.org reutilise des concepts generaux dans chaque type 
de documents, mais avec des variations propres a chacun. Nous avons regroupe les 
principes communs dans le chapitre « Les documents OpenOffice.org », puis decrit 
les aspects specifiques aux documents Writer, Calc et Draw/Impress dans les chapi- 
tres suivants. Dans chacun de ces chapitres, il n'est nul besoin d'effectuer une lecture 
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complete : apres avoir acquis les notions de base, utilisez ensuite le livre comme une 
reference, et n'approfondissez que les sujets qui vous sont utiles. 

La quatrieme partie va au-dela des manipulations de documents pour vous permettre 
de construire des applications elaborees. Vous y apprenez a afficher des dialogues tout 
a fait semblables a ceux des applications classiques, a utiliser une base de donnees et 
des formulaires elabores. Des aspects plus transversaux sont ensuite traites : gestion de 
la configuration, gestion de fichiers depuis l'API, utilisation du Dispatcher, interac- 
tion avec le monde MS-Windows, et diverses methodes bien utiles. 

Les annexes presentent de nombreuses informations complementaires. Nous expli- 
quons ce quest l'API et comment en obtenir des informations pour aller encore plus 
loin. Nous presentons ensuite une liste de routines utilitaires dont certaines ont ete utili- 
sees pour simplifier nos exemples. Nous signalons enfin les ressources Internet incon- 
tournables pour qui souhaite se tenir a jour : il s'agit de forums oil chercher assistance, ou 
de sites fournissant des exemples de macros, des documents explicatifs et des outils. 



Aspects juridiques 

Les descriptions, les exemples et les divers logiciels de cet ouvrage et des fichiers disponibles en telechar- 
gement sont fournis comme potentiellement utiles, mais sans aucune garantie, ni explicite ni implicite, y 
compris les garanties de commercialisation ou d'adaptation dans un but specifique. Les exemples sont 
fournis dans un but d'explication et leurs principes sont librement reutilisables. 
Quelques routines utilitaires sont soumises a la licence LGPL (comme indique en commentaire dans le 
codage, voir le Zip telechargeable). Cette licence, peu contraignante, est decrite sur le site http:// 
www.gnu.org/copyleft/lesser.html. Une traduction non officielle de la licence LGPL est disponible 
sur le site http://www.linux-france.org/article/these/licence/lgpl/lgpl_monoblock.html. 



Changements par rapport a la precedente edition 

Avec cette nouvelle edition, totalement revue et reorganisee, nous avons ajoute des 
notions qui n'avaient pas ete decrites, tenu compte des modifications et ajouts 
apportes par les versions successives d'OpenOffice.org 2 et 3, ameliore de nombreux 
codages, mis a jour les references d'adresses Internet, et signale des outils apparus 
depuis la version precedente de notre livre. 

Pour alleger la lecture, nous avons supprime ce qui etait specifique de l'ancienne version 1 
d'OpenOffice.org, et les limitations propres a la version initiale 2.0. Sauf indication con- 
traire dans le texte, ce qui est decrit est aussi valable pour les dernieres versions 2 
(versions 2.3.1 et plus recentes). Les copies d'ecran sont fakes avec la version 3. 
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Principaux ajouts 

Chapitre 1 : les extensions. 

Chapitre 2 : information sur la compatibilite VBA. 

Chapitre 3 : type Byte, sous-type Deci mal , type Col 1 ecti on, type defini par l'utilisateur. 
Chapitre 4 : boucle For Each. 

Chapitre 5 : operateur Like, fonctions DateDiff, DateAdd, DatePart, Format. 

Chapitre 7 : description complete des options d'export PDF, valeurs d'encodage de 
caracteres pour import et export CSV et texte, proprietes de document definies par 
l'utilisateur. 

Chapitre 8 : surlignement, statistiques du document, tableaux irreguliers en 
version 3, actualiser un document Writer. 

Chapitre 9 : fusion de cellules, filtrage, fonction matricielle, liens vers un autre clas- 
seur, exemples de Listener. 

Chapitre 10 : methodes et proprietes pour gerer un diaporama en cours. 

Chapitre 11 : ajout dynamique des controles de dialogue, dialogues et messages 
multilingues. 

Chapitre 12 : valeurs d'encodage de caracteres pour une base plate, connexion a une 
base non enregistree, publipostage plus detaille. 

Chapitre 13 : description systematique des controles de formulaire, ajout dynamique 
des controles de formulaire, macros dans un document Base, ouvrir et fermer un for- 
mulaire depuis un autre formulaire de fichier Base. 

Chapitre 14 : lire et modifier la configuration OpenOffice.org, ecrire et lire un 
fichier texte encode, formatage par l'API, exemples d'utilisation du Dispatcher. 



Documents disponibles en telechargement 

Sur le site web des editions Eyrolles, www.editions-eyrolles.com, vous trouverez la 
fiche de ce livre, ou vous pourrez telecharger gratuitement un fichier Zip. Ce fichier 
se decompacte dans un repertoire Macros Livre comprenant autant de sous-reper- 
toires que de chapitres donnant des exemples de macros. Les macros d'un chapitre se 
trouvent dans des documents OpenOffice.org, ainsi que les fichiers associes even- 
tuels. La reference du fichier contenant la macro est indiquee en premiere ligne de 
chaque macro reproduite dans cet ouvrage. 
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Avant execution, il vous faudra copier les fichiers necessaires dans un repertoire de 
travail de votre ordinateur, la oil, justement, leur execution est autorisee. 
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Premiere partie 



Introduction a la 
p rog r a m m a t i on 
OpenOffice.org 



Cette premiere partie vous montre l'utilite de la programmation OpenOffice.org a 
travers quelques exemples. Si differents langages de script peuvent etre utilises pour 
les obtenir, Basic est le plus accessible d'entre eux. 

Vous apprendrez comment securiser l'utilisation des scripts ou macros, et 
diverses manieres de declencher un script. Vous ferez connaissance avec l'enregis 
treur de macros Basic, puis avec les interfaces utilisateur propres a chaque langage 
de script supporte (a l'exception de Basic, qui sera le sujet de la partie suivante) 



E a 
Dur 



1 



Les scripts dans 
OpenOffice.org 



Le terme macro evoque plutot le langage Basic, qui sera d'ailleurs notre principal 
langage de programmation dans ce livre. Mais il nest pas le seul, comme nous allons 
le voir. On devrait maintenant employer le terme plus general de script, mais les 
habitudes ont la vie dure, et le terme macro est employe partout dans les interfaces 
utilisateur. 

OpenOffice.org offre differents langages de programmation (langages de script), 
contrairement a la concurrence. Sa structure permet meme d'en rajouter d'autres. 
Nous serons amenes a signaler quelques concepts avances, qui seront plus clairs apres 
lecture du reste du livre. 



De I'automatisation d'OOo a I'application d'entreprise 

Avant de vous lancer dans l'aventure, vous vous demandez peut-etre ce qu'on peut 
bien realiser d'interessant avec OOoBasic et l'API d'OpenOffice.org. Eh bien, tout 
est fonction du besoin. Une « bonne » macro est une macro qui satisfait un besoin, 
qu'il soit recurrent ou ponctuel. II n'est pas necessaire de batir un environnement 
applicatif complet (meme si cela est tout a fait possible) et quelques lignes suffisent 
parfois a rendre des services inestimables au quotidien. 
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Les macros d'OpenOffice.org permettent d'adapter le logiciel a un besoin specifique, 
avec cet avantage indeniable que dans le cas des macros OOoBasic, tout est deja 
integre et pret a rutilisation. OOoBasic offre un cadre d'execution commun pour 
elaborer des additifs logiciels. Une macro « arrivant » sur un poste est certaine de 
retrouver ce cadre de travail, et ce quelle que soit la plate-forme utilisee. 

Des macros pour les utilisateurs d'OpenOffice.org 

Les utilisations des macros sont multiples. On peut bien sur intervenir directement 
sur un document en cours pour reproduire une tache repetitive ou fastidieuse, mais 
aussi federer plusieurs documents pour des traitements transversaux. Bien des utilisa- 
teurs ont leurs propres macros, non publiees, qui leur font gagner du temps dans 
leurs activites quotidiennes, depuis 1' application d'un style de caractere en cliquant 
sur une simple icone jusqu'a la mise en forme de plusieurs documents a la fois. 

Une macro d'interet general peut etre distribute sous la forme d'une extension. Une 
extension est un fichier reconnu par OpenOffice.org qui permet de lui ajouter facile- 
ment une nouvelle fonctionnalite. 

Des applications a part entiere pour l'entreprise 

Un nombre croissant d'entreprises et d'administrations developpent des applications 
internes basees sur OOoBasic etl'API d'OpenOffice.org. Des outils internes a l'API 
peuvent notamment permettre d'envisager une utilisation a travers un reseau voire 
Internet. La encore, de nombreuses fonctionnalites sont presentes en interne. 

Par exemple, si un important fonds documentaire est disponible dans un certain 
format et qu'il devient necessaire d'en effectuer une migration pour obtenir une ver- 
sion PDF des documents, les fonctionnalites d'import/export le permettent. 

Si des donnees sont eparpillees dans plusieurs sources et qu'il devient necessaire de 
les federer voire d'en construire des graphes a intervalles donnes, l'accessibilite a 
l'API de Calc va pouvoir repondre au besoin. 

Si un mailing requiert des interventions particulieres ou s'il devient necessaire de 
recuperer des donnees dans des documents contenant des champs utilisateurs afin de 
les consolider, la encore, l'API et les macros peuvent etre utilisees. 

Enfin, les macros peuvent servir a faire de petits scripts simples completement decon- 
nectes du contexte bureautique, comme des « moulinettes » sur des fichiers texte. 
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Les macros et la securite 

La puissance des macros comporte un revers : des individus peuvent ecrire des docu- 
ments anodins contenant des programmes concus dans un but malveillant. Les utili- 
sateurs de MS-Outlook, MS-Word et MS-Excel en savent quelque chose. En rea- 
lite, il est heureusement rare de recuperer de tels documents, mais beaucoup plus 
courant qu'un correspondant de bonne foi vous envoie un document avec une macro 
de son cru, et que celle-ci provoque des degats dans votre PC ou dans votre configu- 
ration OpenOffice.org. Ainsi, d'une maniere generale, un document destine a etre 
diffuse devra etre lisible sans macro. 

Dans OpenOffice.org, l'utilisateur definit les conditions d'execution des macros a 
partir du menu Outils>Options>OpenOffice.org>Securite. La figure 1-1 reproduit ce 
panneau. 




En fait, tout se passe dans le panneau qui apparait en cliquant le bouton Securite des 
macros, qui concerne tous les scripts, pas seulement Basic. Ce panneau comporte 
deux onglets, le premier est reproduit a la figure 1-2. Les textes explicatifs de chaque 
niveau ne sont pas tous corrects, nous allons voir exactement ce qu'il en est. 



Les differents niveaux de securite 

Ces niveaux de securite ne concernent que les macros contenues dans un document. 
Les macros integrees dans votre exemplaire d'OpenOffice.org sont supposees inof- 
fensives (il s'agit des macros hebergees dans les zones Mes macros et Macros Open- 
Office.org, et des extensions installees). 
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ite des macros 




Figure 1-2 

Onglet Niveau de securite 
des macros 



ecunte | Sources de confiance | 



Niveau de securite tres eleve. 
P Seules les macros provenant d'emplacements de fichiers de confiance peuvent 
etre executees. Toutes les autres macros, qu'elles soient signees ou non, sont 
desactivees. 



Niveau de securite eleve. 
C Seules les macros signees provenant de sources de confiance peuvent etre 
executees. Les macros non signees sont desactivees. 



Niveau de securite moyen. 

Une confirmation manuelle sera demandee avant I'execution de macros 
provenant de sources non securisees. 




Niveau faible 

Ce niveau de securite autorise toute macro, quelle que soit l'origine du document. Ne 
l'utilisez que si vous aimez vivre dangereusement. 



Niveau moyen 

Le niveau de securite moyen vous avertit si le document contenant la macro ne se trouve 
dans aucun de vos repertoires de confiance (voir l'onglet Sources de confiance). Une 
bonne securite consiste a declarer quelques repertoires de confiance, ceux ou vous savez 
que certains documents necessitent des macros. Quand vous recuperez un document 
inconnu, placez-le dans un repertoire ordinaire. Si le document contient des macros, 
OpenOffice.org vous en avertit (figure 1-3 pour des macros signees ou figure 1-4 pour 
des macros non signees) en vous donnant plusieurs possibilites d'action : 

• Fermer la fenetre (case X) desactive I'execution des macros. 

• Dans le cas de la figure 1-3, si vous cochez la case Toujours faire confiance aux 
macros provenant de cette source, les macros seront activees, le certificat sera ajoute 
dans la liste des certificats de confiance (figure 1-7) et la question ne vous sera 
plus posee pour les documents avec des macros portant la meme signature, quel 
que soit leur emplacement. Ne cochez la case qu'apres avoir clique sur le bouton 
Afficher les signatures. En effet, le certificat peut etre invalide, ou le niveau de con- 
fiance faible s'il est delivre gratuitement par Internet. 
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Dans le cas de la figure 1-4, ou si vous ne cochez pas la case de la figure 1-3, vous 
pouvez activer ou non l'execution des macros pour cette fois-ci. Le fait de les 
desactiver n'empeche absolument pas d'ouvrir le document, ni de visualiser les 
instructions avec l'editeur de macros (que nous verrons au chapitre 2). 



Figure 1-3 

Niveau moyen, 

avertissement de macro signee 



□ penOffice.org - Avertissement de securit 



D:\encours\EssaiMacrosSign3.odt 




? document contient des macros de document signes par : 



Afficher les signatures... 

Lcros peuvent contenir des virus. La deactivation des macros 
ocument esttoujours sure. Si vous desactivez des macros, 
s fonctionnalites fournies par les macros de document seront 
:re perdues. 

jjours faire confiance aux macros provenant de cette source 



Figure 1-4 

Niveau moyen, 
avertissement de macro 




z 



Les macros peuvent contenir des virus. La deactivation des macros 
d'un document esttoujours sure. Si vous desactivez des macros, 
certaines fonctionnalites fournies par les macros de document seront 
peut-etre perdues. 



Activer les macros 



Niveau el eve 

Ce niveau autorise l'execution des macros dont le document se trouve dans un des 
repertoires de confiance. Si le document se trouve en dehors de ces repertoires, 
OpenOffice.org considere deux cas : 

• Soit les macros ne sont pas signees : elles sont systematiquement desactivees et 
OpenOffice.org affiche le message d'avertissement de la figure 1-5. 



Figure 1-5 

Niveau eleve, avertissement 
de macro 



□ penOffice.org 3.0 




Ce document contient des macros. 

L'execution de ces macros est desactivee en raison des parametres actifs de 
securite des macros dans Outils - Options - OpenOffice.org - Securite. 
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• Soit les macros sont signees, vous obtenez alors le message de la figure 1-6. 



Figure 1-6 

Niveau eleve, avertissement 
de macro signee 



OpenOffice.org Avertissement de secuiite 




Si vous cochez la case Toujours faire confiance aux macros provenant de cette source, vous 
accedez au bouton Activer les macros. Apres ouverture du document, le certificat sera 
ajoute dans la liste des certificats de confiance (figure 1-7) et la question ne vous sera 
plus posee pour les documents avec des macros portant la meme signature, quel que 
soit leur emplacement. Ne cochez la case qu'apres avoir clique sur le bouton Afficher 
les signatures. En effet, le certificat peut etre invalide, ou le niveau de confiance faible 
s'il est delivre gratuitement par Internet. Si vous ne cochez pas la case, l'execution de 
macros du document est desactivee. 

Niveau tres eleve 

La securite se base exclusivement sur les repertoires de confiance. Les macros de 
documents situes en dehors de ces repertoires sont systematiquement desactivees et 
OpenOffice.org affiche le message d'avertissement de la figure 1-5. 

Les sources de confiance 

Longlet Sources de confiance est reproduit a la figure 1-7. 

La zone du haut liste les certificats de confiance qui representent des signatures 
acceptables pour les macros. Lorsque, sur le message des figures 1-4 ou 1-6, vous 
cochez Toujours faireconfiance aux macros de cette source, le certificat correspondant est 
automatiquement ajoute dans la liste des certificats de confiance. 

La zone du bas liste les repertoires de confiance. Pour chacun, la confiance s'etend a 
toute l'arborescence de sous-repertoires qu'il contient. Evitez de mettre la racine d'un 
disque principal car tout le disque serait alors considere comme de confiance, ce qui 
haurait plus de signification. 
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Figure 1-7 

Onglet Sources de confiance 




Les signatures numeriques 

La creation ou l'importation de certificats permettant de valider une signature nume- 
rique necessite d'autres logiciels comme Firefox et autres navigateurs Internet. Nous 
ne detaillerons pas ici les procedures. 

Se documenter 

Dans I'aide (F1), cherchez dans I'index Signature et Utilisation des signatures numeriques. 

Un document OpenOffice.org peut etre certifie numeriquement par un ou plusieurs 
certificats. Notez qu'avec la version 3 d'OpenOffice.org les documents a signer doi- 
vent etre sauvegardes au format ODF 1.2. On certifie un document avec le panneau 
obtenu par Fichier>Signatures numeriques. Une fois certifie OpenOffice.org calcule une 
signature numerique sur le document. Cette signature de document est indepen- 
dante de la signature eventuelle des macros du document. De maniere similaire, les 
macros d'un document peuvent etre signees avec le panneau de la figure 1-8, obtenu 
avec le menu Outils>Macro>Signature numerique. 

Le processus est le suivant : 

1 Sauvez votre document, sans le fermer. 

2 Ouvrez le panneau de la figure 1-8 et ajoutez un ou plusieurs certificats. 

3 Fermez le document sans le sauver ! 
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Figure 1-8 

Signatures numeriques 
des macros 




Le document peut etre copie ou deplace, il gardera ses signatures. 

Plus tard, apres toute modification du document, repetez exactement le processus, 
car la sauvegarde supprime les signatures pour eviter qu'un tiers ne modifie les 
macros en gardant une apparence de securite. 



L'enregistreur de macros 

L'enregistreur de macros enregistre les sequences de manipulations de l'utilisateur 
sous forme d'une macro, ce qui permet ensuite de reproduire a volonte la meme 
sequence. La methode est tres simple et ne necessite pas de connaissances de pro- 
grammation. 

Comment enregistrer une macro ? 

L'enregistrement est declenche en cliquant sur Outils>Macros>Enregistrer une macro. A 
partir de cet instant, toutes les actions sur le document OpenOffice.org contenu dans 
la meme fenetre sont enregistrees. Vous remarquerez une petite fenetre en avant- 
plan : elle vous permet de terminer l'enregistrement. 

Ayant clique sur cette fenetre de terminaison de macro, un autre panneau apparait. 
Choisissez dans quelle bibliotheque et quel module vous souhaitez sauvegarder votre 
macro. Nous expliquerons plus loin ces termes et ce panneau. Essentiellement, vous 
avez le choix entre un module d'une bibliotheque disponible en permanence dans 
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OpenOffice.org et une bibliotheque propre au document en cours. En general, specia- 
lement pour un debutant, il suffit de choisir la bibliotheque Standard du document en 
cours et de cliquer le bouton Enregistrer (enregistrer la macro). Un nouveau panneau 
apparait, qui vous demande de choisir le nom du module, par exemple Modul el. Main- 
tenant, votre macro est ecrite dans le module et elle a pour nom Macrol ou un nom 
similaire. Vous pouvez changer ce nom dans l'editeur de macros qui s'affiche. 

Notre document exemple Code-02-01.odt contient dans sa bibliotheque Standard une 
sequence realisee avec l'enregistreur de macros : aller a la fin du document, ecrire un 
texte et terminer le paragraphe. Voici le codage obtenu (les lignes blanches sont omises). 

sub BonjourEnregistreur 

rem 

rem define variables 
dim document as object 
dim dispatcher as object 

rem 

rem get access to the document 

document = ThisComponent.CurrentController. Frame 

di spatcher = createUnoServi ce("com . sun . star . frame . Di spatchHel per") 

rem 

dispatcher. executeDispatch(document, ".uno:CoToEndOfDoc", "", 0, ArrayO) 

rem 

dim args2(0) as new com. sun. star. beans. PropertyValue 
args2(0).Name = "Text" 

args2(0) .Value = "L'enregistreur de macros vous salue !" 

dispatcher. executeDispatch(document, ".uno:InsertText", "", 0, args2()) 

rem 

dispatcher. executeDispatch(document, ".uno:InsertPara", "", 0, ArrayO) 
end sub 

Le document exemple contient d'autres scripts realisant exactement la meme chose 
en Basic, JavaScript, BeanShell, Python. En comparant les codages, vous constaterez 
que l'enregistreur de macro produit un codage tres different des autres : en effet il 
n'utilise pas les fonctions de l'API, mais seulement un mecanisme appele dispatch. 

Un outil limite 

L'enregistreur de macros souffre de limitations assez severes : 

• II n'est disponible que sous Writer et Calc. 

• II ne sait que « mimer » des actions de l'utilisateur, et encore, pas toutes. 

• II utilise des commandes peu documentees (les « slot ID »). 

• II ne permet pas d'ecrire des macros interactives. 
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• II produit un codage Basic non optimise qui est assez difficile a lire, sans rapport 
avec un « vrai » codage Basic OpenOffice.org. 

Par ailleurs, mais c'est le principe d'un tel enregistreur, il ne peut produire que du 
codage lineaire (c'est-a-dire qu'il est incapable de faire par exemple une boucle pour 
repeter une action sur une liste d'objets ou de choisir entre plusieurs alternatives). 

Pour avoir plus de possibilites, il faut ecrire soi-meme les instructions de la macro, ce 
qui necessite de connaitre un langage de programmation et l'API OpenOffice.org. 
C'est la voie qui est developpee dans ce livre. 

II est cependant des cas ou l'enregistreur de macros nous sera utile : parfois l'API ne 
permet pas certaines manipulations que peut realiser l'enregistreur. II est alors pos- 
sible de resoudre la difficulte en combinant un codage Basic avec les instructions 
creees par l'enregistreur. 



Les differents langages de script 

Depuis la version 2, OpenOffice.org integre plusieurs langages de script, et pas seule- 
ment Basic. Chaque langage a ses avantages et ses defauts, et un programmeur experi- 
mente preferera celui qui est le plus adapte a son projet, ou meme a une partie du projet. 
Nous appellerons macro ou script tout programme realise avec un de ces langages. 

Certains details de cette section sont destines aux lecteurs ayant acquis une bonne 
connaissance de la programmation avec OpenOffice.org. 

Basic OpenOffice.org 

Basic sera notre langage de developpement dans ce livre, mais nous ne l'aborderons 
qu'avec le chapitre2. Pour vous donner un avant-gout, voici une petite macro 
BonjourBasi c, que vous trouverez dans la bibliotheque Li braryl du document exemple 
Code-02-01 . odt. Elle realise l'equivalent de l'exemple de l'enregistreur de macros. 

Sub BonjourBasic 

Dim monDocument As Object, monTexte As Object, monCurseur As Object 
monDocument = Thi sComponent 
monTexte = monDocument .Text 
monCurseur = monTexte. createTextCursor 
monCurseur .gotoEnd(fal se) 

monTexte. insertString(monCurseur, "Basic et l'API vous saluent !", false) 

monTexte . i nsertCont rol Character (monCu rseur , 

com . sun . star . text . Cont rol Characte r . PARAGRAPH_BREAK , f al se) 

End Sub 
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Particularites des autres langages de script 

Les langages autres que Basic sont geres par le Scripting Framework, qui fait l'objet 
d'un chapitre complet dans le Developer's Guide (documentation en anglais) dispo- 
nible en ligne a l'adresse suivante : 

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ 
OpenOffice.org_Developers_Guide 

Une variable predefinie XSCRIPTCONTEXT est disponible dans un script. Cet objet 
expose trois methodes : 

• getDocumentO renvoie l'objet document en cours. 

• getDesktopO renvoie l'objet application OpenOffice (equivalent du Basic 
Star-Desktop). 

• getComponentContextO renvoie le contexte, necessaire pour appeler certaines 
methodes. 

Les dialogues, que nous verrons au chapitre 11, peuvent etre appeles par un script 
quelconque, et les evenements de dialogue peuvent aussi etre traites par un script. 

II est plus facile de developper un script non Basic dans Mes macros, quitte a le trans- 
ferer ensuite dans un document avec adaptation eventuelle. 

Java compile 

OpenOffice.org peut executer des scripts en Java compile (fichiers .jar). Mais il 
n'existe pas de panneau Macros correspondant, et leur installation devra etre faite 
manuellement par un programmeur confirme. 

JavaScript 

Langage bien connu des createurs de sites web, JavaScript est utilise ici comme lan- 
gage de programmation independant de toute page web. Chaque macro JavaScript 
est contenue dans un fichier portant 1' extension . j s, stocke dans un repertoire biblio- 
theque. Le panneau Macros JavaScript de la figure 1-9 est obtenu par le menu 
Outils>Macros>Gerer les macros>JavaScript. Ici la macro se trouve dans la bibliotheque 
Library3 du document CodeOl-Ol.odt. 

Vous pouvez creer une nouvelle bibliotheque ou une nouvelle macro dans celle selec- 
tionnee. Le bouton Ed iter affiche le contenu de la macro dans la fenetre de l'editeur Open- 
Source Rhino (voir figure 1-10). II offre des possibilites d'evaluation de variables, de pas-a- 
pas et de point d'arret ; mais il n'y a ni coloration syntaxique ni aide en ligne sur les instruc- 
tions. II souffre actuellement de defauts redhibitoires (Issue 70176, Issue 70215) qui con- 
duisent a le deconseiller et preferer un editeur separe pour modifier le fichier. 
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Figure 1-9 

Panneau Macros JavaScript 




Figure 1-10 

Editeur de JavaScript 
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} vnd.sun.star.tdoc:/2/ScriptsjjavascriptJLibrary3jBonjourJavaScri| 



1 importClass (Packages. com. sun. star.uno.UnoRuntime) ; 

2 importClass (Packages. com. sun. star. text.XTextDocument) ; 
importClass (Packages. com. sun. star. text.XText) ; 
importClass (Packages. com. sun. star . text. XTextRange) ; 

oDoc = XSCRIPTCONTEXT. getDocumentf ) ; 

xTextDoc = UnoRuntime. guerylnterf ace (XTextDocument,oDoc) ; 
xText = xTextDocaetTextn; 




Quand vous creez une nouvelle macro JavaScript, OpenOffice.org ecrit automati- 
quement un codage de type HelloWorld. S'il peut servir d'exemple sous Writer, il est 
inutilisable sous Calc, Draw, etc. 

Void le codage du script BonjourJavaScript. js. Comme pour Java, il est necessaire 
d'obtenir explicitement chaque interface dont on utilise une methode. Par contre il 
n'y a pas de typage de donnees. 

"i mportCl ass (Packages . com . sun . star . uno . UnoRunti me) ; 

i mportCl ass (Packages . com . sun . star . text .XTextDocument) ; 

"importCl ass (Packages . com . sun . star . text .XText) ; 

i mportCl ass (Packages . com . sun . star . text .XTextRange) ; 
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oDoc = XSCRIPTCONTEXT.getDocumentO ; 

xTextDoc = UnoRuntime.queryInterface(XTextDocument,oDoc) ; 
xText = xTextDoc.getTextO ; 
xTCursor = xText . createTextCursorO ; 
xTCursor.gotoEnd(false) ; 

xText . i nsertStri ng( xTCursor, "JavaScript vous salue ! " , false); 
xText . i nsertControl Character (xTCursor, 

Packages . com . sun . star . text . Control Character . PARAGRAPH_BREAK , f al se) ; 

Les arguments passes a une macro JavaScript sont recuperes dans une variable glo- 
bale predefinie ARGUMENTS qui est un tableau de valeurs de type Object. Par exemple, 
ici on recupere l'objet evenement transmis par le declenchement d'un bouton de 
formulaire : 

evt = ARGUMENTS [0] ; 



Pour aller plus loin 

Site web de Rhino, en anglais : 

► http://www.mozilla.org/rhino/ 
Un site web francais sur JavaScript : 

► http://www.toutjavascript.com/ 



BeanShell 

BeanShell est une sorte de Java interprete et plus simple au niveau des declarations. 
Chaque macro BeanShell est contenue dans un fichier portant l'extension .bsh, 
stocke dans un repertoire bibliotheque. Le panneau Macros BeanShell de la figure 1-11 
est obtenu par le menu Outils>Macros>Gerer les macros>BeanShell. Ici la macro se trouve 
dans la bibliotheque Library2 du document CodeOl-Ol.odt. 



Figure 1-11 

Panneau Macros BeanShell 
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Vous pouvez creer une nouvelle bibliotheque ou une nouvelle macro dans celle selec- 
tionnee. Le bouton Editer affiche le contenu de la macro dans la fenetre de l'editeur 
BeanShell (voir figure 1-12). C'est un editeur rustique qui n'offre ni police a espace- 
ment fixe, ni coloration syntaxique, et aucun outil de mise au point. 



Figure 1-12 

Editeur de BeanShell 



E BeanShell Debug Window: /2/SciipU/beanshell/Library2/BonjourBeanShell.bsh/ucb/ 
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6 import drafts. com. sun. star.script.provider.XScriptContext; 
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import com.sun.star.uno.UnoRuntime; 
import com. sun. star.uno.XComponentContext; 
in p n rt c n in s u n sta r.fra in e XD e s Hop, 
import com.sun.star.frame.XModel; 



import com. sun. star.text.XTextDocument; 
import com.sun.star.text.XText; 
import com.sun.star.text.XTextRange; 

oDoc = XSCRIPTCONTEXT.getDocumentO; 

xTextDoc = (XTextDocument) UnoRuntime.querylnterface(XTextDocument.class,oDoc); 
xText = xTextDoc.getTextO; 

com.sun.star.text.XTextCursor>:TCursor = sText.createTextCursorO; 
xTCursor gotoEndffalse); 

xText.insertString(xTCursor, "BeanShell vous salue I " , false); 

xText InsertControlCliaracterfxTCursor, com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK.fal' 
return 0 



.IE 









Close 



Comme avec JavaScript, lorsque vous creez une nouvelle macro BeanShell, Open- 
Office.org presente automatiquement un codage type « Hello World ». II peut servir 
d'exemple sous Writer, mais il est inutilisable sous Calc, Draw, etc. 

Void le codage du script BonjourBeanShel 1 .bsh. Comme pour Java, il est necessaire 
d'obtenir explicitement chaque interface dont on utilise une methode. Le principal 
interet de BeanShell reside dans sa capacite a utiliser des codages Java tout en profi- 
tant d'un langage plus souple pour les types de donnees. 

i mport com . sun . star . uno . UnoRunti me ; 
i mport com . sun . star . uno .XComponentContext ; 
i mport com . sun . star . frame . XDesktop ; 
import com. sun. star. frame. XModel ; 

import drafts . com . sun . star . scri pt . provi der .XScri ptContext ; 

i mport com . sun . star . text . XTextDocument ; 

import com.sun.star.text.XText; 

i mport com . sun . star . text . XText Range ; 
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oDoc = XSCRIPTCONTEXT.getDocumentO ; 

xTextDoc = (XTextDocument) UnoRuntime.queryInterface( 

XTextDocument . cl ass , oDoc) ; 
xText = xTextDoc.getTextO ; 

com. sun. star. text. XTextCursor xTCursor = xText.createTextCursorO ; 
xTCursor.gotoEnd(false) ; 

xText . i nsertStri ng( xTCursor, "BeanShell vous salue ! " , false); 
xText . i nsertControl Character (xTCursor, 

com . sun . star . text . Control Character . PARAGRAPH_BREAK , f al se) ; 

return 0; 

Les arguments passes a une macro BeanShell sont recuperes dans une variable glo- 
bale predefinie ARGUMENTS, qui est un tableau de valeurs de type Object. Par exemple, 
ici on recupere l'objet evenement transmis par le declenchement d'un bouton de 
formulaire : 

evt = (ActionEvent) ARGUMENTS [0] ; 



Plus d'informations 

► http://www.beanshell.org/ 



Python 

Python est un langage Open Source, tres puissant et original. Les points remarqua- 
bles, par rapport a Basic, sont les suivants : 

• Lindentation obligatoire facilite la relecture. 

• Les variables ne sont pas declarees mais leur usage est controle. Elles peuvent 
changer de type dynamiquement. 

• Les algorithmes sont plus simples grace aux fonctions puissantes incluses dans 
Python et ses modules principaux. 

• La gestion des erreurs est celle des langages modernes. 

• La programmation objet facilite la conception de programmes complexes. 

Python permet la creation de composants UNO, contrairement a Basic. Un compo- 
sant UNO ajoute un service API qui peut etre utilise par tout autre langage. 

Chaque macro Python est une fonction declaree dans un fichier ayant 1' extension . py, 
stocke dans le sous-repertoire Scripts/python/ ou un sous-repertoire de celui-ci. Le 
panneau Macros Python de la figure 1-13 est obtenu park menu Outils>Macros>Gerer les 
macros>Python. Ici la macro se trouve dans la bibliotheque Library 3 du document 
CodeOl-01 . odt. Un fichier source peut comporter plusieurs fonctions appelables. 
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Figure 1-13 

Panneau Macros Python 




Vous remarquerez sur la figure 1-13 que les boutons Creer, Editer, Renommer, Sup- 
primer sont inactifs ; ce qui ne laisse en fait que la possibilite d'executer un codage 
existant. OpenOffice.org n'offre pas encore d'editeur pour Python. Le developpeur 
de macros Python doit done utiliser un editeur externe pour modifier son fichier et 
travaillera dans Mes macros. II n'y a pas d'outil de mise au point, et les messages 
d'erreur apportent malheureusement peu d'informations utiles. 

Les programmeurs Python noteront qu'il est necessaire d'utiliser l'interpreteur 
Python integre a OpenOffice.org, et que 1'IDLE n'est pas non plus utilisable pour 
executer un script dans OpenOffice.org. Ces limitations sont dues au manque de 
developpeurs. Souhaitons que quelques developpeurs ou des entreprises genereuses 
proposent leur aide a la communaute OpenOffice.org afin de mieux integrer ce lan- 
gage. Dans l'etat actuel, les avantages de Python dans OpenOffice sont plutot 
reserves aux programmeurs experimentes sachant de surcroit lire l'anglais. 

Voici le codage du script BonjourPython. L'utilisation de l'API OpenOffice.org est 
tres semblable a Basic. 

Faites attention a ne pas oublier deux particularites de Python : respecter la casse 
(majuscules/minuscules) pour les noms de variables, et mettre des parentheses vides 
dans tout appel d'une methode sans argument. 

from com. sun. star. text. Control Character import PARAGRAPH_BREAK 

def BonjourPython( ): 

"""Ecrit un texte dans le document Writer""" 
monDocument = XSCRIPTCONTEXT. getDocumentO 
monTexte = monDocument .Text 
monCurseur = monTexte. createTextCursorO 
monCurseur .gotoEnd(Fal se) 
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monTexte . i nsertStri ng(monCurseur , "Python vous salue !", False) 
monTexte . i nsertControl Character (monCurseur , PARAGRAPH_BREAK, Fal se) 
return None 



Pour plus (('informations 

Deux pages web de reference, en anglais, a lire attentivement pour developper des macros en Python : 

► http://wiki.services.openoffice.org/wiki/Python_as_a_macro_language 

► http://udk.openoffice.org/python/python-bridge.html/ 
Le site web Python, en anglais : 

► http://www.python.org/ 
L'Association francophone Python : 

► http://www.afpy.org/ 



Executer une macro depuis OpenOffice.org 

Une macro s'integre dans les mecanismes de votre exemplaire d'OpenOffice.org, 
ajoutant ainsi une fonctionnalite, soit dans le contexte d'un type de document, soit 
pour tous les documents. Vous pouvez alors la declencher de differentes facons. 

Executer une macro depuis le menu Outils 

Avec le menu Outils>Macros>Executer la macro vous obtenez le panneau reproduit a la 
figure 1-14. 

Figure 1-14 

Panneau du 
Selecteur de macro 



Selectionnez la bibliotheque contenant la macro souhaitee. Ensuite, 
selectionnez la macro sous 'Nom de la macro'. 




Introduction a la programmation OpenOffice.org 

Premiere partie 



Remarquez qu'il existe trois arbres contenant chacun des bibliotheques de macros : 

• Mes macros correspond aux macros que vous avez ajoutees et qui sont disponibles 
pour toute application OpenOffice.org et depuis tout document. 

• Macros OpenOffice.org contient des bibliotheques de macros fournies par Open- 
Office.org. Dans une installation reseau, l'administrateur peut y ajouter des biblio- 
theques qui seront alors disponibles pour tous les utilisateurs OpenOffice.org. 

• Code02-01 est le nom d'un document que nous avons ouvert. Un document peut 
aussi contenir des bibliotheques de macros. 

Developpez l'arborescence jusqu'a trouver le module contenant votre macro, selec- 
tionnez-la, et cliquez sur le bouton Executer. Dans la figure 1-15 nous avons choisi 
une macro Basic contenue dans Mes macros. 



Figure 1-15 

Selection d'une macro Basic 




Ce meme panneau permet de choisir une macro ecrite dans un autre langage que 
Basic. II en existe quelques-unes fournies avec l'installation, dans la branche Macros 
OpenOffice.org. La figure 1-16 vous en montre plusieurs : 

• hell owo rid . bsh est une macro BeanShell ; 

• he! 1 oworl d . j s est une macro JavaScript ; 

• Hell oWo rid. pri ntHW est une macro en Java compile ; 

• HelloWorldPython est une macro en Python. 

Vous remarquerez que, sauf pour les macros Basic, il est possible d'afficher un com- 
mentaire descriptif de la macro. Le document exemple CodeOl-Ol.odt, disponible 
dans le Zip telechargeable sur le site des editions Eyrolles, contient lui aussi des 
macros ecrites dans ces langages. 

Vous retrouverez la meme structure arborescente dans les autres manieres de declen- 
cher une macro par l'interface utilisateur. 
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Figure 1-16 

Macros ecrites 
en divers langages 




Executer une macro depuis un raccourci clavier 

Avec le menu Outils>Personnaliser vous obtenez le panneau Personnaliser, qui comporte 
un onglet Clavier. Cet onglet est represente sur la figure 1-17. 
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Pour affecter une macro a un raccourci clavier afin de pouvoir ensuite l'executer d'une 
simple combinaison de touches, il faut commencer par determiner si la macro sera 
disponible pour une application particuliere (ici tous les documents Writer), ou pour 
toute application OpenOffice.org (Calc, Draw, Writer, etc). Selon ce choix, le cadre 
Raccourcis clavier presente la liste des raccourcis possibles, en indiquant ceux deja uti- 
lises. Choisissez un raccourci inutilise ou supprimez un raccourci deja attribue. 

Passez ensuite a la minuscule fenetre Categorie. II faut utiliser les ascenseurs pour 
l'explorer. Dans la partie inferieure sont regroupees les macros dans la branche Macros 
OpenOffice.org. Cliquez sur les signes + et vous trouvez : 

• user : correspond a l'arborescence Mes macros vue avec le menu Outils. 

• share : correspond a l'arborescence Macros OpenOffice.org du menu Outils. 

• un nom de document : regroupe les macros eventuellement presentes dans un 
document actuellement ouvert. Attention, il faut jamais utiliser une macro de 
document ! En effet, le raccourci sera valable pour tout document. 

En cliquant successivement pour developper l'arborescence, vous finissez par faire 
apparaitre dans la fenetre Fonctions une liste de noms de macros. Une fois que le bon 
raccourci et la bonne commande sont tous deux selectionnes dans les panneaux du 
haut et du bas, cliquez sur le bouton Modifier. La touche ou combinaison de touches 
s'affiche dans la fenetre Clavier et le nom de la macro s'inscrit en face du raccourci. 
Cliquez sur OK pour refermer la boite de dialogue. 

Dans votre document, saisissez un paragraphe, puis testez la macro en l'invoquant 
par son raccourci. A l'appel du raccourci clavier, la macro s'execute. 

Executer une macro avec un bouton de barre d'outils 

Vous pouvez egalement lancer votre macro en cliquant sur un nouveau bouton dans 
une des barres d'outils. 

Cliquez sur la fleche descendante tout au bout a droite sur la barre d'outils. Dans le 
menu contextuel, choisissez Personnaliser la barre d'outils. Vous obtenez le panneau de 
la figure 1-18. 

Choisissez d'enregistrer dans OpenOffice.org ou dans une des applications (ici 
Writer). Cliquez sur la position de votre futur bouton, puis cliquez sur Ajouter. Vous 
obtenez le panneau de la figure 1-19. 

Le choix de la macro s'effectue comme pour un raccourci clavier. Vous aurez sans doute 
envie d' affecter une icone a ce nouveau bouton. Dans le panneau de la figure 1-18 cli- 
quez sur le bouton Modifier puis choisissez Changement d'icone dans le menu. 
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Figure 1-18 

Personnaliser 
une barre d'outils 
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Executer une macro par une entree de menu 

OpenOffice.org vous permet de modifier les elements dans une liste de menu. II est 
ainsi possible d'aj outer un element qui declenchera une macro. Avec le menu 
Outils>Personnaliser vous obtenez le panneau Personnaliser, qui comporte un onglet 
Menus, represente sur la figure 1-20. 



Figure 1-20 

Personnaliser 

une entree de menu 




Choisissez d'enregistrer l'entree de menu dans 1' application (ici, Writer) ou dans un 
document ouvert. Le reste de la procedure est identique a celle presentee a la section 
precedente. 

Executer une macro depuis une extension 

Une extension peut apporter une nouvelle barre d'outils, ou modifier une barre 
d'outils existante, ou encore ajouter des entrees de menu ; tout depend du concepteur 
de l'extension. Une fois installee, les macros de l'extension peuvent etre declenchees 
avec les nouveaux boutons ou les nouvelles entrees de menu. 
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Executer une macro depuis un document 

Un simple bouton de formulaire depose sur une page de document Writer, Calc ou Draw 
permet de declencher une macro. Les controles de formulaire utilisent tres frequemment 
des macros, comme nous le verrons au chapitre 13. Une forme dessinee dans Writer, 
Calc, Draw, Impress peut declencher une macro lorsque l'utilisateur clique dessus. 

Sur une page de document Writer, vous pouvez inserer un champ permettant de 
declencher une macro par hyperlien. Pour cela, dans le menu Inser- 
tion>Champs>Autres, cliquez sur l'onglet Fonctions et dans le cadre Type de champ, cli- 
quez sur Executer la macro. Choisissez votre macro, puis tapez le texte du lien dans la 
zone Annotation, et inserez. 

Dans Calc, il est possible de creer (avec une macro) votre fonction de calcul pour 
l'utiliser dans une formule de cellule. Nous verrons au chapitre 9 comment proceder. 
Notez egalement que le controle de validite d'une cellule peut appeler une macro en 
cas d'entree non valide. 

Executer une macro sur un evenement 

Pour certains usages, il est parfois interessant de declencher automatiquement une 
macro sur un evenement tel que l'ouverture ou la fermeture d'un document. Pour 
cela, nous utilisons l'onglet Evenements du panneau Personnaliser (voir la figure 1-21). 



Figure 1-21 

Declencher une macro 
sur un evenement 
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Determinez si 1' affectation doit concerner OpenOffice.org ou le document ouvert. 
Choisissez I'evenement. Cliquez sur le bouton Macro. Le panneau Selecteur de macro 
apparait, la suite est identique aux cas precedents. La figure montre qu'une macro est 
deja affectee a I'evenement Demarrage de I'application. 

Bien d'autres evenements peuvent faire l'objet d'un traitement par macro, par 
exemple un clic de souris, une touche enfoncee, etc. 



Executer une macro en ligne de commande 

II est parfaitement possible de lancer OpenOffice.org pour simplement executer une 
macro, sans passer par l'interface utilisateur. La syntaxe differe selon le systeme 
d'exploitation. Nous decrirons surtout l'appel d'une macro Basic sous MS-Windows, 
puis nous verrons comment executer des macros d'autres langages. Enfin, nous 
signalerons les particularites propres a Linux. 

Cette section necessite des connaissances de base sur les programmes en ligne de 
commande (MS-DOS ou Unix Shell). Nous supposons en outre que vous avez une 
connaissance minimale du Basic OpenOffice.org, sinon nous vous conseillons de 
vous reporter auparavant au chapitre 2. 

Sous Windows 

Lancer une macro Basic residente 

On appelle « residente » une macro qui se trouve dans une des bibliotheques de Mes 
macros ou Macros OpenOffice.org, et qui est done independante de tout document. 
Pour l'executer, il faut indiquer successivement les elements suivants dans la ligne de 
commande : 

1 Le chemin d'acces et le nom de 1' executable d'OpenOffice.org (soffice.exe). 
Notons que ce chemin depend du systeme d'exploitation, de la version et des con- 
ditions d'installation d'OpenOffice.org. 

2 Le parametre optionnel -headless si on souhaite empecher l'affichage de tout 
message a destination de l'utilisateur. 

3 Une sequence de caracteres qui se presente sous la forme du mot macro suivi du 
nom de la bibliotheque, du nom du module, du nom de la macro, et de ses 
arguments : 

macro:///maLib.monModule.maMacro(Argl, Arg2, . . .) 
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Ressources 

Dans le Zip telechargeable, vous trouverez dans le dossier des macros de ce chapitre, les fichiers corres- 
pondents a nos exemples. 

Dans Mes Macros, creez la bibliotheque maBiblil et le module monModule. Dans ce 
dernier, ecrivez la macro suivante, ou faites un copier-coller de la meme macro qui se 
trouve dans le fichier CodeOl-02 .odt : 

' ecrit un fichier texte comportant n fois le caractere c 
Sub bavard(c As String, n As Integer) 
Dim f As Integer 
f = FreeFile 

open "C:\essaiMacro.txt" for Output As f 

Write #f, Time & " bavard a dit : " & String(n, c) 

close #f 

msgbox "bavard a termine" 
end sub 

Cette macro ecrit l'heure courante et un texte dependant de la valeur de ses argu- 
ments. Adaptez eventuellement le chemin du fichier resultat essai Macro . txt a votre 
propre configuration. 

Realisez ce fichier batch (fichier LanceBavardl.bat) contenant ceci (l'instruction 
principale doit etre ecrite en une seule ligne). 

rem lancement de la macro 

"C:\Program Files\OpenOf fice.org 3\program\soffice.exe" 

"macro: ///maBiblil. monModule. bavard (A, 20)" 
pause 

Modifiez si besoin le chemin d'acces a soffice, il depend de la version Open- 
Office. org utilisee. Mettez ce fichier batch dans un repertoire ou OpenOffice.org 
autorise les executions de macros. 

Arretez l'application OpenOffice.org, y compris le lanceur. Executez le fichier batch. 
La fenetre MS-DOS va s'ouvrir, puis le logo de demarrage d'OpenOffice.org va 
s'afficher et, apres un certain temps, le message « bavard a termine » apparaitra dans 
un petit panneau. Cliquez sur OK, puis terminez 1' execution du batch en appuyant sur 
une touche. Verifiez que le fichier essai Macro . txt est bien ecrit. 



Introduction a la programmation OpenOffice.org 



Premiere partie 



Realisez un deuxieme fichier batch, (LanceBavard2 . bat) contenant cette variante : 
rem lancement de la macro 

"C:\Program Fi 1 es\OpenOf fi ce . org 3\program\soffice.exe" 

-headless "macro:///maBiblil.monModule.bavard(B, 15)" 
pause 

Arretez l'application OpenOffice.org, y compris le lanceur. Executez le fichier batch. 
La fenetre MS-DOS va s'ouvrir et, apres un certain temps, affichera l'attente. Aucun 
autre message n'est apparu. Terminez l'execution du batch en appuyant sur une touche. 
Verifiez que le fichier essai Macro . txt est bien ecrit avec cette deuxieme commande. 

Lorsque l'argument -head! ess est employe, les eventuelles boites de dialogue de OOo, 
comme la confirmation de lancement des macros, recoivent la reponse par defaut. 

Ouvrez un document OpenOffice.org quelconque et relancez le meme fichier batch 
LanceBavard2.bat. Cette fois-ci, le message « bavard a termine » s'affiche, malgre 
l'option -headless. 

Arguments d'appels de la macro 

Comme vous l'avez constate, le premier argument est considere comme une chaine 
d'un seul caractere ; le deuxieme est aussi une chaine de caracteres, mais Basic la con- 
vertit en une valeur numerique valide pour le parametre n de la macro. 

Une chaine de caracteres est transmise telle quelle, sans ajouter de guillemets, sous 
Windows XP. Sous d'autres versions de MS-Windows, il peut etre necessaire 
d'ajouter des guillemets. II n'est pas possible de transmettre une chaine de caracteres 
comportant un guillemet ou une virgule, et les lettres accentuees sont modifiees. 

On peut transmettre a la macro les arguments d'appel du fichier batch, par exemple : 
"macro : ///maBi bl i 1 . monModul e . bavard(%l , %2) " 

Lancer une macro Basic contenue dans un document 

Si le batch appelle une macro contenue dans un document OpenOffice.org la 
methode differe sur plusieurs points : 

• On doit ajouter le chemin d'acces au document s'il n'est pas deja charge. 

• L'argument macro doit comporter le nom court, sans extension, du document, 
sous cette forme (attention au nombre de caracteres/): macro ://monDoc/ 
maLib.monModule.maMacro(Argl, Arg2, . . .) 

• Le document ne se fermera pas automatiquement. 
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Sur le dernier point, il est possible d'ecrire a la fin de la macro une instruction fer- 
mant le document, voir le chapitre 7. 

Realisez ce fichier batch (LanceBavard3 . bat) : 
rem lancement de la macro 

"C:\Program Fi 1 es\OpenOf fi ce . org 3\program\soffice.exe" 

"CodeOl-02 . odt" "macro : //Code01-02/Standard . monModul e . bavard (C , 20) " 
pause 

Mettez ce batch ainsi que le fichier CodeOl-02 .odt (disponible dans le Zip telechar- 
geable) dans un meme repertoire, qui doit etre le repertoire courant pour la ligne de 
commande. 

Arretez l'application OpenOffice.org, y compris le lanceur. Executez le fichier batch. La 
fenetre MS-DOS va s'ouvrir, puis le document va s'afficher et, apres un certain temps, le 
message « bavard a termine » apparaitra dans un petit panneau. Cliquez sur OK. Le 
document reste ouvert. Lexecution du batch ne reprend qua la fermeture d'Open- 
Office.org. Verifiez que le fichier essaiMacro.txt est bien ecrit. Loption -headless 
donnerait le meme resultat. 

Si le document contenant la macro est deja charge, le fichier batch est un peu sim- 
plify (LanceBavard4.bat) : 

rem lancement de la macro 

"C:\Program Fi 1 es\OpenOf fi ce . org 3\program\soffice.exe" 
"macro : //Code01-02/Standard . monModul e . bavard (D , 20) " 
pause 

Chargez au prealable le document CodeOl-02 . odt. Executez le fichier batch. La 
fenetre DOS va s'ouvrir et, apres un certain temps, le message « bavard a termine » 
apparaitra dans un petit panneau. Cliquez sur OK. Le batch reprend son execution (et 
pause). Le fichier reste ouvert. 

Lancer un script autre que Basic 

Pour lancer un script d'un langage quelconque, il faut employer le Scripting Framework, 
qui a deux limitations quand on l'utilise depuis un batch : 

• On ne peut lancer qu'un script « resident » (situe dans Mes macros ou dans Macros 
OpenOffice.org). II est impossible de lancer un script d'un document. 

• On ne peut pas transmettre d'argument au script. 
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L'argument du programme sof f i ce . exe est une chaine de caracteres dont la struc- 
ture generale est : 

vnd . sun . star . scri pt : al pha?l anguage=beta&l ocati on=gamma 

Respectez les majuscules et minuscules pour tous les caracteres. Nous employons les 
mots al pha, beta, gamma pour designer des termes que nous allons expliciter. 

• Le mot beta est a remplacer par le nom du langage de script, exemples : Java, 
JavaScript, BeanShell, Python. 

• Le mot gamma est a remplacer par le terme user si le script se trouve dans Mes 
macros, ou par le terme share si le script se trouve dans Macros OpenOffice.org. 

• Le mot al pha est a remplacer par une sequence dependant du langage. 

Pour un script JavaScript ou BeanShell cree avec l'interface utilisateur, al pha se com- 
pose du nom de bibliotheque, d'un point, et du nom du fichier avec son extension. 

Hell oWorl d . hel 1 oworl d . bsh 

Pour un script Python, al pha se compose du chemin vers le fichier python, en adres- 
sage relatif par rapport au repertoire python/, ensuite un caractere $, et enfin le nom 
de la fonction a appeler. 

tata/exempl e . py$maFoncti on 

Quand un script est appele par commande, il recoit un argument. Cet argument n'a 
aucune utilite, mais il faut en tenir compte dans la declaration de la fonction appelee 
(Python ou macro Java). Cet argument parasite n'a pas de consequence sur les 
macros JavaScript ou BeanShell, car elles ne sont pas declarees comme des fonctions. 

Voici un exemple de ligne batch (HelloJavaScri pt . bat) appelant le script JavaScript 
Hello World qui se trouve dans Macros OpenOffice.org. Ouvrez un nouveau document 
Writer avant de lancer le batch car ce script ecrit un texte dans le document Writer 
courant. 

"C:\Program Files\OpenOf fice.org 3\program\soffice.exe" 
"vnd . sun . star . scri pt : Hel 1 oWorld . hell oworl d . js? 
language=JavaScri pt&l ocati on=share" 

Basic peut lui aussi etre lance via le Scripting Framework, mais cela n'a pas d'interet, 
et implique une syntaxe encore differente. 

Pour terminer sur ce point, signalons enfin que l'appel d'un script d'une extension 
installee utilise un argument plus complexe. 
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Sous Linux 

Le principe est le meme que sous MS-Windows. Les chemins suivront evidemment 
la syntaxe Unix, les arguments d'un shell seront obtenus par $1 etc. 

II faut ajouter dans le fichier shell une redirection vers un terminal X. Faites atten- 
tion aux guillemets. 

' export DISPLAY=":0.0" 
/us r/bi n/sof f i ce -headl ess "macro : ///maBi bl i 1 . monModul e . bavard("$l, 
15")" 



Les extensions 



De quoi s'agit-il ? 

Le concept d'extension remplace et ameliore considerablement le concept d'add-on 
des versions anciennes d'OpenOffice.org tout en restant compatible avec lui. Une 
extension est un fichier qui permet d'etendre les fonctionnalites d'OpenOffice.org 
(par exemple l'export au format LaTeX). Le nom d'un fichier extension a mainte- 
nant pour extension . oxt, mais les anciennes versions utilisent . zi p ou . uno . pkg. 

Vous pouvez creer des extensions vous-meme, ou profiter de celles qui sont disponibles 
sur un site web. Soyez prudent dans ce dernier cas : une extension peut potentielle- 
ment, comme toute macro, provoquer des degats, intentionnels ou non. En installant 
une extension, vous acceptez implicitement son execution, quel que soit le niveau de 
securite que vous avez choisi. La communaute OpenOffice.org a cree un site pour 
regrouper les extensions disponibles, ce qui facilite leur evaluation et reduit les risques : 

http://extensions.services.openoffice.org/ 

Vous y trouverez de tres nombreuses extensions telechargeables, la plupart gratuites, 
certaines payantes. Bien entendu, la qualite et l'utilite des extensions est tres variable. 

Une extension peut se limiter a installer un fichier de configuration. C'est le cas des 
dictionnaires ecrits pour OpenOffice.org. 

Une extension est souvent un moyen pour diffuser facilement une bibliotheque de 
scripts sur differents postes de travail. Elle peut simplement contenir une seule 
macro Basic, ou un ensemble de macros, mais ce nest pas limitatif : tous les langages 
de script que nous avons vus peuvent etre utilises, ainsi que des bibliotheques de code 
objet compile. Si necessaire, une extension peut comporter des parties codees avec 
differents langages de programmation et plusieurs bibliotheques. 
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Une extension peut apporter un composant UNO, cree en Java, C++ ou Python. Ce 
composant peut etre un nouveau service qui enrichit l'API, ou un add-in pour Calc, 
ou encore un add-in pour diagrammes. 

En pratique, les extensions elaborees necessitent de modifier l'interface utilisateur 
afin de les rendre plus conviviales. Aussi, une extension peut : 

• ajouter une barre d'outils avec plusieurs boutons ayant des icones specifiques ; 

• ajouter ou supprimer des boutons dans des barres d'outils existantes ; 

• ajouter une entree ou un sous-menu dans l'entree Outils>Add-ons ; 

• ajouter ou supprimer de nouvelles entrees ou meme une arborescence de sous- 
menus dans les menus principaux (Fichier, Edition, Affichage, etc.) ; 

• ajouter des pages qui seront integrees au systeme d'aide OpenOffice.org ; la page 
correspondant au contexte etant appelee comme pour une fonctionnalite de 
l'application. 

Ces ajouts et modifications peuvent etre propres a chaque application d'Open- 
Office.org concernee (Writer, Calc, Writer-HTML, etc). Par exemple, un bouton 
n'apparait que pour Calc, un autre pour Writer, Calc, Draw et Impress. 

Ajoutons que, pour permettre une diffusion internationale, tout le systeme d'exten- 
sion est multilingue : il est possible de preparer tous les textes (menus, pages d'aide, 
etc.) pour plusieurs langues. S'ils sont disponibles, les textes apparaitront automati- 
quement dans la langue de l'interface utilisateur. 

D'autres mecanismes facilitent la gestion d'extensions d'envergure professionnelle : 

• un identifiant unique, specifique a l'extension (pour eviter les conflits de noms 
entre auteurs d'extensions) ; 

• un numero de version ; 

• un nom « commercial » ; 

• une icone symbolisant l'extension dans le gestionnaire des extensions ; 

• un texte descriptif affiche par le gestionnaire des extensions ; 

• un texte de la licence du produit, affiche a l'installation ; 

• un controle d'adequation entre l'extension et le poste utilise (version d'Open- 
Office.org, plate-forme materielle) ; 

• l'ajout de pages d'options specifiques dans le menu Outils>Options ; 

• un systeme de recherche de mise a jour vers une version plus recente de 
l'extension ; 

• des liens vers le site de l'editeur du logiciel ; 

• un lien vers un site affichant les notes de livraison. 
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Installer une extension 

Quand une extension est installee sur un seul poste, les scripts sont visibles dans la 
section Mes Macros. Dans une installation OpenOffice en reseau, le responsable reseau 
a la possibilite d'installer une extension en mode partage, accessible depuis tous les 
postes. Les scripts de l'extension apparaissent alors dans Macros OpenOffice.org. Sur un 
systeme multi-utilisateur comme Windows XP Home, depuis OpenOffice.org 
version 3.0 vous pouvez installer l'extension pour un utilisateur ou pour tous. 



Installation depuis OpenOffice.org 

Le gestionnaire des extensions permet d'ajouter ou de supprimer tres facilement des 
extensions. Vous y accedez par le menu Outils>Gestionnaire des extensions. Le panneau 
obtenu (figure 1-22) liste les extensions deja installees. Celles comportant un petit 
cadenas sont installees pour tous les utilisateurs. 



Figure 1-22 
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II suffit de cliquer sur le bouton Ajouter et de choisir le fichier extension. Le panneau 
qui apparait (figure 1-23) vous donne le choix de l'installer pour un seul utilisateur 
ou pour tous les utilisateurs. Le meme panneau sert a supprimer une extension ou a 
voir s'il existe des mises a jour pour les extensions installees. 

A partir de la version 3.0, il est possible d'installer une extension en la lancant depuis 
un gestionnaire de fichiers, par exemple avec un double-clic. 
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Figure 1-23 

Installer une extension 



i Assurez-vous qu'aucun utilisateur ne travaille avec le meme OpenOffice.org 

N *\f^ lors de I'installation d'une extension pour tous les utilisateurs dans un 
environnement multi utilisateur. 

Pour qui souhaitez-vous installer cette extension ? 



[ Seulement pour moi ^| Pour tous les uttlis: 



Installation depuis la ligne de commande 

Le responsable informatique qui prefere I'installation en ligne de commande, lancera 
la commande unopkg qui se trouve dans le sous-repertoire program/ du repertoire 
d'installation d'OpenOffice.org. Dans ces exemples des principaux modes de lance- 
ment nous n'avons pas ecrit le chemin complet du fichier monExtensi on . oxt. 

*** ajouter une extension pour un utilisateur 
unopkg add monExtensi on . oxt 

*** ajouter une extension pour tous les utilisateurs 
unopkg add --shared monExtensi on . oxt 

*** supprimer une extension a parti r de son identifiant unique 

unopkg remove xxx.yyyy.zzz. monExtensi on 

unopkg remove --shared xxx.yyyy.zzz.monExtension 

*** lancer unpkg en mode interactif 

unopkg gui 

*** interactif, en designant le fichier (OOo 3.0 minimum) 

unopkg gui monExtensi on . oxt 

*** lister les options de unopkg 

unopkg -h 

Attention, pendant I'installation pour tous les utilisateurs le responsable informa- 
tique doit s'assurer que personne d'autre n'utilise OpenOffice.org. 



Concevoir une extension 

Une extension se presente sous la forme d'une archive Zip qui regroupe differents 
fichiers. Realiser une extension comportant toutes les possibilites que nous avons 
decrites represente parfois un effort plus important que le codage du script, en parti- 
culier pour une extension multilingue avec pages d'aide. Une telle extension com- 
porte souvent des dizaines de fichiers. La plupart d'entre eux sont des fichiers XML 
dont les contenus sont codifies selon des syntaxes precises. 

Certains developpeurs creent une extension en se basant sur une extension existante. 
Pour cela, il faut : 

1 dezipper 1' archive ; 

2 modifier les fichiers XML manuellement avec un editeur ; 
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3 ajouter et remplacer les fichiers propres a la nouvelle extension (bibliotheque 
Basic, fichiers images, etc) ; 

4 et enfin zipper le dossier. 

Pour les experts Documentation officielle 

Les extensions sont decrites techniquement dans le Developer's Guide, section Extensions. Ces pages, en 
anglais, sont disponibles a cette adresse : 

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Extensions/ 
Extensions 



En pratique creer ainsi une extension est penible et long si on veut profiter des possi- 
bilites existantes. Si vous ne connaissez pas bien la syntaxe des differents sous- 
fichiers de 1' extension, c'est l'echec est assure. Nous presentons ici trois manieres plus 
efficaces de creer une extension. 

Exporter une extension minimale 

Un codage Basic realise dans une bibliotheque Basic autre que Standard est exportable 
en tant qu' extension simple, en cliquant sur un bouton dans le gestionnaire de macros 
Basic, comme sur la figure 1-24. Une fois l'export effectue, supprimez la bibliotheque 
Basic existante, puis installez l'extension, ce qui retablira la bibliotheque. 



Figure 1-24 

Creer une extension a partir 
d'une bibliotheque Basic 




Ainsi, il est facile d'ajouter ou de supprimer une bibliotheque de macros pour diffe- 
rents utilisateurs. Ceux-ci pourront les employer dans leurs codages ou configurer 
manuellement leur poste pour les appeler d'un clic sur un bouton de barre d'outils, ou 
par un raccourci clavier. En contrepartie on n'utilise aucune des possibilites avancees 
decrites plus haut. 
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L'outil BasicAddonBuilder 

L'outil Open Source BasicAddonBuilder a ete elabore par Paolo Mantovani. II sert a 
creer une extension a partir d'une bibliotheque de macros Basic, et a ajouter une 
barre d'outils et des menus. Un Assistant tres bien concu facilite sa mise en ceuvre 
(voir les figures 1-25 et 1-26). 



Figure 1-25 

BasicAddonBuilder, etape 1 
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Figure 1-26 
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Pour la petite histoire, BasicAddonBuilder est une extension, realisee en plusieurs 
langues, dont le francais. Cet outil est ideal pour une extension comportant des 
macros Basic, une barre d'outils et quelques menus. L'inconvenient est que, dans la 
version actuelle, si vous voulez modifier quelque chose vous devez re-executer toutes 
les etapes de 1' Assistant sans vous tromper, ce qui peut devenir penible. 

Pour telecharger BasicAddonBuilder, rendez-vous a la page : 

http://wiki.services.openoffice.org/wiki/Extensions_Packager 

L'outil Extension Compiler 

Un des auteurs de ce livre a cree l'outil Open Source Extension Compiler, seulement dis- 
ponible en anglais. II permet de realiser tous types d'extensions, pas seulement Basic, et 
supporte tous les mecanismes connus, ce qui implique en contrepartie un effort de com- 
prehension plus important. Pour le telecharger, rendez-vous a l'adresse suivante : 

http://wiki.services.openoffice.org/wiki/Extensions_Packager 

L'outil se presente sous la forme d'un modele de document Writer (extension .ott). 
En l'ouvrant par un double-clic, vous obtenez un nouveau document que vous allez 
personnaliser. Commencez par le sauver sous le nom de votre future extension, et dans 
un repertoire dedie. Dans ce repertoire (ou dans des sous-repertoires), vous devrez 
mettre toutes les bibliotheques que votre extension apporte (Basic, Python, etc), les 
fichiers images, et tous autres fichiers specifiques quelle utilise. Ainsi, tous les ele- 
ments necessaires a la creation de l'extension se trouvent dans le repertoire dedie. 

Ce document est a la fois un outil realise en Basic, la documentation de l'outil, et le 
support sur lequel vous decrivez votre extension. Vous allez ecrire dans ce document : 

• une succession lineaire de macro-instructions (en fait des appels de sous-pro- 
grammes Basic) dans une macro deja preparee ; le document decrit la syntaxe 
d'utilisation de chaque macro-instruction ; 

• si vous le souhaitez, un ou plusieurs textes destines a etre affiches par l'extension 
(descriptions, licences, pages d'aide), en une ou plusieurs langues pour chacun. 

Void a titre d'exemple le debut des instructions Basic necessaires pour compiler une 
extension multilingue. 

beginDescriptionCorg . bmarcel 1 y . ExtExampl e" , "1.0", "user") 
begi nDependenci es 

set00oDependency("2.4", "OpenOffice.org 2.4.0 mi nimal ") 
endDependencies 

setExtensionDescri ption("en , f r") 
setLi cense("en , fr", "", "user", True) 
setDisplayName("en", "Example of an extension") 
setDisplayName("fr", "Exemple d'une extension") 
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setHelp("en, fr") 
endDescription 

beginAnnexes 

useLibrary ("Basic" , "basTest4/") 
endAnnexes 

beginAddonUI 
beginAddonMenu 

begi nMenu 

begi nTi tl es ("Writer") 

setTi tl e("Call i ng scripts", "en") 
setTitle("Appel de scripts", "fr") 
endTi ties 
begi nMenuItems 
begi nCommand 
begi nTi ties 

setTitle("Basic : display time", "en") 
setTitle("Basic : afficher l'heure", "fr") 
endTi tl es 

setURLC'Basic", "basTest4", "Modulel", "WhatTi melslt") 
endCommand 
begi nCommand 
begi nTi tl es 

setTitle("Basic : Hello", "en") 
setTitle("Basic : Hello", "fr") 
endTi ties 

setURLC'Basic", "basTest4", "Modulel", "HelloBas") 

setlmage(" Images/green Page") 
endCommand 
addSeparator 
rem etc. . . 

La compilation s'effectue en lancant l'execution du programme Basic. Tous les 
fichiers de configuration necessaires sont crees, l'ensemble est zippe, et le fichier 
extension est obtenu apres quelques secondes. S'il detecte une erreur grave, le compi- 
lateur fournit un message diagnostic et stoppe. II suffit alors de corriger la ligne en 
cause et de relancer la compilation. 

Le compilateur signale par un message d'avertissement les incompatibilites poten- 
tielles entre les options choisies et le numero de version minimal d'OpenOffice.org 
accepte. En effet, comme les fonctionnalites liees aux extensions ont ete introduites 
au fil des versions successives d'OpenOffice.org, il faut eviter qu'un utilisateur n'ins- 
talle une extension sur une version incompatible. 

Si vous decidez par la suite d'ameliorer votre extension, il vous suffira de reprendre le 
document, d'y apporter les modifications necessaires et de le recompiler pour obtenir 
la nouvelle version de l'extension. 
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Conclusion 

Apres ce tour d'horizon des scripts dans OpenOffice.org, il est temps d'aborder 
Basic, le langage le plus couramment utilise, ainsi que son environnement de deve- 
loppement integre. Ceci nous permettra de voir le contenu d'une macro, de l'editer et 
de l'executer. 
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Le langage 
OOoBasic 



:C1- 

int 

... 



II existe de nombreuses variantes du langage Basic. lis se ressemblent, mais chacun 
a ses particularites. L'application OpenOffice.org integre un langage Basic sped 
fique, ainsi qu'un environnement de developpement pour creer et mettre au point 
vos programmes en OOoBasic. 

Meme si vous connaissez deja un autre Basic, par exemple Visual Basic™ qui lui est 
proche, prenez le temps de parcourir les chapitres de cette partie. En cas de pro- 
bleme d'execution, relisez-la, car elle contient bien des details importants et pas 
toujours indiques dans la documentation officielle. 

A l'intention des neophytes, nous indiquons aussi quelques regies de bonne p 
grammation, non pas pour vous enlever le plaisir de programmer, mais au contra 
pour vous eviter echecs et decouragements. 
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Le Basic OpenOffice.org est le langage que nous utilisons dans les exemples de ce 
livre. Apres l'avoir situe parmi ses confreres, nous verrons l'environnement de deve- 
loppement integre (EDI en francais ou IDE en anglais), outil essentiel pour ecrire et 
mettre au point aisement les codages en Basic. Nous commencerons par nous fami- 
liariser avec ses differents menus et comprendre leur utilite pour developper des pro- 
grammes Basic. Nous aborderons alors les regies de syntaxe de ce langage, ainsi que 
quelques bonnes pratiques de programmation. 



Premier apercu du langage OpenOffice.org Basic 

Le langage Basic de la suite OpenOffice.org est parfois appele en abrege OOoBasic 
afin de le distinguer des autres langages Basic, et nous reprendrons ce terme. La 
societe Sun prefere le terme StarOffice Basic ou StarBasic, car elle diffuse la suite 
StarOffice™ qui est basee sur OpenOffice.org. 

OOoBasic, langage de script d'OpenOffice.org 

Son nom rappelle un des plus anciens langages, Basic, concu a l'origine pour des 
debutants en programmation disposant de moyens informatiques parfois tres limites. 
En realite OOoBasic n'a plus qu'un lointain rapport avec son ancetre. Bien qu'il reste 
d'un abord simple, OOoBasic est un langage de programmation moderne permettant 
de developper des applications sophistiquees. C'est un langage de programmation 
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modulaire : fini les numeros de lignes, les GOTO et la programmation « spaghetti » ; les 
macros sont regroupees en modules et en bibliotheques reutilisables. 

OOoBasic est con9u pour ecrire, lire et modifier des documents OpenOffice.org en 
utilisant l'API (interface de programmation d'application) propre a OpenOffice.org. 
II est entierement integre a OpenOffice.org, et ce dernier comporte un environne- 
ment de developpement integre (EDI) servant a ecrire les macros et a les mettre au 
point. Lexecution du codage est immediate, sans necessiter de compilation explicite. 
Ceci en fait une base tres pratique (et gratuite) pour s'initier a la programmation ou 
pour verifier rapidement un codage utilisant une fonction de l'API. 

OOoBasic nest pas un langage de programmation autonome : il a besoin d'Open- 
Office.org pour s'executer. C'est un langage oriente vers 1'automatisation de besoins 
de bureautique, il ne remplace pas les langages generalistes comme C++, Java, 
Delphi, Python et autres. Les langages generalistes offrent des structures de donnees 
plus elaborees et generalement des bibliotheques de fonctions utilitaires dans divers 
domaines. lis seront done plutot employes dans un cadre applicatif plus global que 
les documents OpenOffice.org. II est bien plus facile de recourir a l'API par le biais 
d'OOoBasic (ou Python, Delphi) qu'avec Java ou C++. En contrepartie, seuls ces 
derniers permettent d'intervenir au cceur de l'API pour y ajouter ou modifier des 
fonctionnalites. II serait done faux de croire que « qui peut le plus peut le moins » : 
une tres bonne connaissance de l'informatique, du concept UNO et de l'anglais ecrit 
sont necessaires pour cela. 

Les macros OOoBasic peuvent etre integrees soit dans un document, soit dans 
OpenOffice.org. Elles sont transportables d'un ordinateur a un autre, et meme dis- 
tribuables sur un reseau de machines. Elles sont executables sur tous les systemes 
d'exploitation reconnus par OpenOffice.org, ce qui constitue un atout important 
pour les echanges de documents. 

II existe divers moyens pour declencher une macro : manuellement, en cliquant sur 
un bouton d'une barre d'outils, en cliquant sur un bouton dans un document, en uti- 
lisant une entree de menu, avec un raccourci clavier, lors de divers evenements 
comme le chargement ou la fermeture du document, ou automatiquement de 
maniere invisible. 

Les manipulations de documents OpenOffice.org se font normalement a travers 
l'API, quel que soit le langage utilise. OOoBasic n'y fait pas exception, et malgre son 
apparence simplicite, il est capable d'utiliser pratiquement toutes les fonctionnalites 
offertes par l'API OpenOffice.org. Ainsi, les concepts decrits dans cet ouvrage sont 
largement reutilisables avec un autre langage. 
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OOoBasic et VBA 

Lorsqu'un utilisateur ou une entreprise decide d'utiliser OpenOfEce.org a la place de la 
suite MS-Office, la conversion des documents Word et Excel existants est effectuee 
generalement correctement ; en revanche, les macros Visual Basic for Application 
(VBA™) dans ces documents ne sont pas executables telles quelles avec OOoBasic. La 
raison est qu'il n'y a pas d'equivalence simple entre les deux langages car les realisations 
logicielles sous-jacentes sont differentes bien que les possibilites soient comparables. 
Plus precisement, VBA integre a la fois un langage de programmation Basic et des 
fonctions d'acces a 1API MS-Office presentees sous la forme de pseudo-instructions. 

Les instructions du langage OOoBasic lui-meme sont tres similaires et souvent iden- 
tiques a celles du langage Visual Basic. II existe toutefois de nombreuses differences 
de details, qui peuvent necessiter une modification de 1'algorithme. Si vous con- 
naissez deja VBA, ne faites pas de supposition sur OOoBasic : lisez attentivement la 
description du Basic dans ce livre, vous decouvrirez des nombreuses differences, sou- 
vent subtiles, mais dont vous devez tenir compte. 

Lequivalent des fonctions d'acces a 1API MS-Office est l'ensemble des services de 
1API d'OpenOffice.org, accessibles depuis differents langages de programmation. 
Contrairement a l'editeur de code de VBA, l'editeur de OOoBasic ne propose pas 
l'auto-completion, c'est-a-dire la proposition en cours de frappe des proprietes et 
methodes des objets de 1API. Loutil Xray, decrit dans l'annexe A, permet de les affi- 
cher, mais seulement en ajoutant une instruction dans la macro a executer. Les objets 
de 1API OpenOffice.org sont souvent tres differents, et seule une bonne connais- 
sance des deux principes de programmation permettra d'ecrire un algorithme equiva- 
lent, lorsque c'est possible. Leffort intellectuel de conversion pouvant etre assez 
important, il est souhaitable de se demander si le document est encore utile, et dans 
l'affirmative, de determiner quel est le but a atteindre avec des macros, plutot que 
tenter une conversion instruction par instruction ou macro par macro. 

Le Basic avec un gout de VBA 

Avant d'aborder la description du Basic OpenOffice, il est necessaire de preciser de 
quoi nous allons parler. En effet, au fil des evolutions d'OpenOffice.org, differentes 
variantes sont apparues dans le but de permettre une meilleure compatibilite avec 
VBA de Microsoft. 

Dans les premieres versions d'OpenOffice.org 2, Sun MicroSystems avait introduit 
deux modificateurs permettant une meilleure compatibilite avec VBA : la declaration 
Opti on Compati bl e, et l'instruction Compati bi 1 i tyMode. 

A la meme epoque, Novell a demarre un projet ambitieux visant a executer directe- 
ment des macros VBA existantes. Les resultats de ce projet sont integres dans les 
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developpements OpenOffice.org a partir de la version 2.4.1. Les modificateurs de 
Sun sont remplaces par une seule declaration Option VBASupport en tete du module, 
avant toute declaration de macro ou de donnee. 

Option VBASupport 1 
Cette option a quatre effets : 

• Dans le module considere, l'analyseur syntaxique est legerement modifie pour 
traiter la syntaxe VBA. Par exemple, l'appel d'une routine avec plusieurs argu- 
ments ne doit pas les englober de parentheses. 

• Dans le module considere, certains objets VBA sont reconnus, comme 
Acti veSheet, Thi sWorkBook, etc. 

• Certaines instructions VBA deviennent disponibles (par exemple InStrRev) dans 
ce module. 

• Pour une meilleure compatibilite, le comportement de Basic change pour certai- 
nes instructions (Mid, Di r, RmDi r, par exemple). Ceci peut causer des comporte- 
ments bizarres si votre code utilise a la fois des modules avec VBASupport et des 
modules OOoBasic. 

En fonction des options du menu Outils>Options>Chargement/Enregistrement>Pro- 
prietes VBA, les macros d'un document MS-Office sont soit ignorees, soit mises en 
commentaires dans des modules de macros. A partir de la version 3.0, une option 
permet de rendre executables les macros d'un document Excel, en utilisant le meca- 
nisme de compatibilite developpe par Novell. II en sera bientot de meme pour les 
documents Word. 

En pratique, il existe de tres nombreuses differences mineures entre OOoBasic et 
VBA qui empechent l'execution directe de macros VBA. Elles ne sont pas toujours 
documentees par Microsoft, mais elles sont utilisees. Par exemple, le mot-cle Name 
peut etre employe comme nom de variable dans VBA, mais pas dans OOoBasic qui 
le considere comme un mot reserve. Novell est ainsi conduit a multiplier les 
« petites » ameliorations du mode de compatibilite a mesure qu'il decouvre des pro- 
blemes en analysant des macros VBA. Ces modifications sont introduites au fil des 
versions mineures d'OpenOffice.org. 

II ne faut pas s'illusionner sur cette option de compatibilite : les implementations de 
MS-Office et de VBA d'une part, et de OOoBasic et de l'API OpenOffice d'autre 
part, different dans leur principe et dans leur logique. Une parfaite compatibilite est 
impossible. Le seul interet de cette option est de permettre d'executer avec peu ou 
pas de modifications des macros VBA simples, et de reduire ainsi le travail de por- 
tage, ce qui est deja tres appreciable. Cependant, un programmeur devra effectuer 
manuellement la conversion des macros complexes ou trap eloignees des principes 
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OpenOffice. II faudra alors repenser les macros et les recrire en ayant une parfaite 
connaissance de l'API OpenOffice. 

C'est pourquoi nous n'utiliserons pas l'option de compatibilite VBA. Ce livre ne 
decrit que le Basic specifiquement OpenOffice.org, encore appele OOoBasic, et 
nous i'utiliserons pour montrer les possibilities de l'API propre a OpenOffice.org. 



Premiers pas dans I'environnement de developpement Basic 



Anatomie de la fenetre Macros Basic 

Creez un nouveau document Writer, sauvegardez-le et gardez-le ouvert. Ouvrez le 
menu Outils>Macros>Gerer les macros>OpenOffice.org Basic. Vous obtenez le panneau 
reproduit a la figure 2-1. 




L'aspect exact de l'arborescence au-dessous de Macro de depend des macros qui sont 
disponibles dans votre environnement OpenOffice.org. Vous aurez toujours une 
racine Mes macros et une racine Macros OpenOffice.org. Ces deux racines contiennent 
des macros disponibles tant qu'OpenOffice.org est charge sur votre ordinateur. II est 
important de savoir qu'elles correspondent a un seul conteneur de bibliotheques, 
appele sof f i ce dans les versions precedentes. Nous utiliserons ce terme a differents 
endroits de ce livre, car il est encore utilise dans la documentation technique. 

Le panneau affiche aussi une racine pour chaque document ouvert : chacune est un 
conteneur de bibliotheques de macros. Vous remarquerez un element mis en valeur 
dans la figure, Standard, qui est une branche du document premierEssai .odt ; cette 
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bibliotheque par defaut est toujours presente, meme vide. De meme, il existe une 
bibliotheque nommee Standard dans Mes macros. 

Cliquez sur le bouton Gerer.... Vous obtenez un autre panneau, Gestion des macros de 
OpenOffice.org Basic qui comporte trois onglets : Modules, BoTtes de dialogue, et Biblio- 
theques (voir la figure 2-2). Restez sur l'onglet Modules. 

Figure 2-2 

Onglet Modules : 
les bibliotheques 
de codage Basic 



En utilisant l'ascenseur et en cliquant sur les +, explorez l'arborescence. Dans notre 
exemple, nous avons developpe le premier niveau de Macros OpenOffice.org. Nous 
avons ainsi affiche la liste de ses bibliotheques de codage Basic. 

Examinez encore l'arborescence de la figure 2-2 : la bibliotheque Euro est de couleur 
blanche pour signifier quelle n'est pas chargee actuellement. Pour executer une 
macro d'une bibliotheque, celle-ci doit etre chargee. 

Double-cliquez sur l'icone de la bibliotheque Euro. Une arborescence apparait, 
comme sur la figure 2-3, et l'icone devient jaune. Vous venez de charger la biblio- 
theque Euro. Remarquez qu'une fois chargee, il n'est pas possible de la decharger. En 
fait, il faudrait fermer completement OpenOffice.org pour cela, ou fermer le docu- 
ment si la bibliotheque appartient a un document. 

L'arborescence de la bibliotheque Eu ro nous montre des noms de modules (on peut 
effectivement choisir des noms plus parlants que Modulel, Module2, etc.). Le codage 
Basic est memorise dans ces modules. 

Cliquez maintenant sur l'onglet BoTtes de dialogue. Cette page n'affiche que les 
modules de dialogue existant dans chaque bibliotheque (voir figure 2-4). Chaque 
module contient une boite de dialogue. 

Les dialogues affichent des informations et posent des questions a l'utilisateur pour 
obtenir des reponses de maniere semblable aux panneaux d'OpenOffice.org. Nous 
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Figure 2-3 

Les modules 

de la bibliotheque Euro 




Figure 2-4 

Onglet Dialogue : 

les bibliotheques de dialogue 




expliquerons comment creer des boites de dialogue au chapitre 11. II est important 
de savoir que les dialogues ne sont pas reserves au langage Basic, ils peuvent etre uti- 
lises depuis d'autres langages de script. Cependant, pour des raisons d'implementa- 
tion, il existe encore une bibliotheque de modules Basic, meme vide, pour chaque 
bibliotheque de dialogue. L'EDI de Basic affiche les modules de codage et de dia- 
logue. Notez les noms de racines : Mes boTtes de dialogue et Boites de dialogue Open- 
Office.org correspondent aux dialogues disponibles tant qu'OpenOffice.org est charge 
sur votre ordinateur. Un document peut lui aussi contenir des dialogues. 

Passons maintenant a l'onglet Bibliotheques du panneau Gestion de macros. II est 
reproduit a la figure 2-5. 

Ce panneau affiche initialement les bibliotheques de Mes macros et boTtes de dialogue. 
La liste deroulante au-dessus permet de choisir les bibliotheques communes Macros 
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Figure 2-5 

Onglet Bibliotheques 
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et boTtes de dialogue OpenOffice.org ou celles de chaque document ouvert. Les boutons 
servent a gerer les bibliotheques, ainsi que nous le preciserons un peu plus loin. 

• Le bouton Nouveau cree une nouvelle bibliotheque, dont on peut choisir le nom. 

• Le bouton Supprimer supprime definitivement la bibliotheque dont la ligne est 
mise en evidence. 

• Le bouton Mot de passe permet de chiffrer le contenu des macros d'une bibliothe- 
que, de sorte que seules les personnes connaissant le mot de passe puissent les lire 
et les modifier. 

• Le bouton Exporter effectue une sauvegarde de la bibliotheque dans un fichier ou 
un repertoire. 

• Le bouton Importer sert a inserer une bibliotheque existante. 



Souplesse et modularity de 1'organisation 

Resumons-nous : 

• II existe plusieurs conteneurs de bibliotheques : sof f i ce et un conteneur par 
document. 

• Le conteneur sof f ice est visuellement separe en Mes macros et Macros Open- 
Off ice.org. Les dialogues de soffi ce sont visuellement separes en Mes boTtes de dia- 
logue et BoTtes de dialogue OpenOffice.org. 

• Chaque conteneur peut renfermer plusieurs bibliotheques, dont au moins une 
bibliotheque appelee Standard. 

• Chaque bibliotheque peut renfermer plusieurs modules (jusqu'a 16 000 selon 
l'aide en ligne ; nous avons seulement teste avec 250 modules de plus de 
30 000 caracteres chacun !). 
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• Chaque module peut renfermer plusieurs macros et comporter jusqu'a 
65 000 caracteres. 

Pourquoi une telle organisation a tiroirs ? Pour des raisons de souplesse et de modu- 
larite. En effet, un utilisateur chevronne recourt souvent a de nombreuses macros, 
pour des cas d'utilisation differents. Les macros concernant un domaine commun 
seront done regroupees dans differents modules d'une meme bibliotheque. D'une 
bibliotheque a l'autre, il est possible de reprendre les memes noms de macros sans 
risquer d'interference ; chaque bibliotheque peut done etre developpee de maniere 
totalement independante. 

Pourquoi un conteneur sof f i ce ? Si vous avez besoin d'une macro disponible dans 
tous les documents, par exemple une macro qui permet d'intervertir deux lettres sur 
un texte, vous la mettrez dans une bibliotheque de sof f ice. Si votre macro est utile 
dans un seul document, vous la placerez dans ce dernier. 

Le conteneur sof f ice est compose de deux sous-ensembles, memorises dans des 
fichiers situes dans deux sous-repertoires differents : 

• user/basi c/ dans le repertoire des donnees utilisateur, 

• et Basis/share/basic/ dans le repertoire du programme OpenOffice.org 
version 3. 

lis correspondent respectivement aux noms Mes macros et Macros OpenOffice.org dans 
l'interface utilisateur. Le premier sous-ensemble correspond aux macros, que vous 
souhaitez disponibles au niveau de votre application OpenOffice.org. Le second cor- 
respond aux macros mises a disposition des utilisateurs d'une installation reseau. 
Dans ce cas, ils ne peuvent que les utiliser, pas les modifier. 



A RETENIR Bibliotheque Standard 

Chaque bibliotheque de macros Standard est systematiquement chargee par OpenOffice.org, quand le 
document qui le contient est charge. La bibliotheque Standard du conteneur sof f i ce est toujours 
chargee. Ceci rend disponibles toutes les macros de ces bibliotheques. OpenOffice.org ne charge pas sys- 
tematiquement toutes les bibliotheques pour eviter de consommer inutilement la memoire du systeme. 
Attention : les bibliotheques de dialogues (meme Standard) ne sont jamais chargees systematiquement. 



Gerer les bibliotheques de macros Basic 

Nous allons maintenant nous interesser aux possibilites qu'offre le panneau Gestion de 
macros, onglet Bibliotheques. 
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Renommer une bibliotheque 

II est possible de renommer une bibliotheque existante (autre que Standard) a partir 
de l'onglet Bibliotheques. D'abord, assurez-vous que la bibliotheque est chargee, 
comme indique plus haut. Ensuite, cliquez sur le nom de la bibliotheque a 
renommer. Toute la ligne est mise en evidence. Cliquez a nouveau apres une seconde, 
seul le nom de la bibliotheque est alors mis en evidence : vous pouvez maintenant le 
modifier. Cliquez ensuite ailleurs pour que le nouveau nom soit pris en compte. 
Comme la procedure est un peu risquee, exportez la bibliotheque avant de la 
renommer pour en avoir une copie de sauvegarde. 

Exporter une bibliotheque 

Dans l'onglet Bibliotheques du panneau Gestion de macros, choisissez le conteneur sou- 
haite dans la liste deroulante : un document, Mes macros et boTtes de dialogue, ou 
Macros et boTtes de dialogue OpenOffice.org. 

Selectionnez une des bibliotheques listees, a 1' exclusion de la bibliotheque Standard, 
qui ne peut etre exportee. Cliquez sur le bouton Exporter, une boite de dialogue 
(figure 2-6) vous demande de choisir une methode d'exportation : soit sous forme 
d'un repertoire contenant des fichiers, soit sous forme d'une extension (on obtient 
alors un fichier en .oxt). Apres ce choix, il vous sera demande de preciser le reper- 
toire ou le nom du fichier. 

Figure 2-6 

Exporter une bibliotheque 



L'exportation sous forme de repertoire sert a modifier manuellement certains des 
fichiers, lorsque vous avez la competence requise. L'exportation sous forme d'extension 
quant a elle facilite la sauvegarde d'une bibliotheque. Vous pouvez alors la re-importer 
par la suite depuis le meme panneau de gestion, comme explique ci-dessous. 

Si vous souhaitez distribuer une bibliotheque de macros sur plusieurs ordinateurs, il 
est preferable de 1' exporter sous forme d'extension. Sur les autres ordinateurs elle sera 
installee depuis le menu Outils>Gestionnaire des extensions. Ainsi le gestionnaire des 
extensions indiquera clairement si cette extension (done la bibliotheque) est installee 
ou non, et facilitera une mise a jour. 



Exporter la bibliotheque 



f» Exporter en tant qu extension 

xporter comme bibliotheque BASIC 
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Importer une bibliotheque 

Affichez l'onglet Bibliotheques du panneau Gestion de macros. Prenez soin de choisir le 
conteneur souhaite dans la liste deroulante : un document, ou Mes macros et boTtes de 
dialogue. Vous ne pouvez pas ajouter de bibliotheque dans Macros et boTtes de dialogue 
OpenOffice.org. 

Cliquez sur le bouton Importer, un panneau de recherche de fichier s'affiche. Recher- 
chez sur votre ordinateur un document OpenOffice.org contenant une bibliotheque 
de macros. Dans l'exemple de la figure 2-7, le document contient trois 
bibliotheques : Rechercher, Remplacer et Standard. 



Figure 2-7 

Importer une bibliotheque 




La case a cocher devant chaque bibliotheque vous permet de la charger ou non dans 
le conteneur courant. La case a cocher Remplacer les bibliotheques existantes ecrase le 
contenu entier d'une bibliotheque de meme nom dans le conteneur cible ; sinon, la 
bibliotheque existante restera inchangee. Ceci est particulierement important pour la 
bibliotheque Standard, qui contient souvent diverses macros. C'est pourquoi il est 
preferable de grouper les macros dans des bibliotheques specialisees. 

Si vous souhaitez importer une bibliotheque qui a ete exportee « comme biblio- 
theque Basic », cherchez le repertoire du nom de la bibliotheque, puis dans ce reper- 
toire, choisissez le fichier script. xlb ou le fichier dialog.xlb, indifferemment. Si 
vous voulez importer une bibliotheque qui a ete exportee « en tant qu' extension », 
choisissez le fichier extension obtenu par l'export. 

Copier une bibliotheque 

II est possible de copier une bibliotheque de Mes macros vers un document, et inverse- 
ment. La description precedents vous indique la marche a suivre dans les deux cas. 
Pour copier une bibliotheque d'un document vers un autre document, il suffit de 
combiner les deux descriptions. 
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Proteger une bibliotheque par mot de passe 

Par defaut, vos bibliotheques et macros sont consultables et editables par l'utilisateur. 
Si dans la majeure partie des cas cela ne pose pas de probleme particulier, il est par- 
fois necessaire de proteger cet acces par un mot de passe pour proteger des donnees 
confidentielles qui s'y trouveraient (un mot de passe d'un document par exemple) ou 
pour eviter des alterations par megarde. 

Pour proteger une bibliotheque, il suffit de se rendre dans le gestionnaire de macros, 
onglet Bibliotheque. Si une bibliotheque est choisie, le bouton Mot de passe... de la 
figure 2-5 est accessible. En cliquant dessus, vous pourrez mettre un nouveau mot de 
passe ou en changer un existant. Une cle apparait a cote du nom de la bibliotheque 
dans le gestionnaire de macros. 

Le contenu des fichiers sera alors chiffre (crypte). Pour que la securite soit effective, 
il faut fermer le document contenant cette bibliotheque, ou fermer OpenOffice.org 
si la bibliotheque est dans soffice. Les macros contenues seront ainsi executables, 
mais un mot de passe sera demande pour acceder a l'EDI et en voir le code source. 

Depuis un bouton, un menu ou un raccourci, on peut appeler une macro situee dans 
une bibliotheque protegee. II n'est pas necessaire de connaitre le mot de passe. La 
bibliotheque sera chargee automatiquement, mais ne sera pas pour autant visible 
dans l'EDI. 

De meme, on peut appeler depuis une macro une macro se trouvant dans une biblio- 
theque protegee, sans utiliser le mot de passe. II suffit de charger la bibliotheque, et 
de connaitre le nom de la macro de la bibliotheque et ses arguments. 

Deplacer un module d'une bibliotheque a une autre 

Affichez l'onglet Modules du panneau Gestion de macros. Par un simple glisser- 
deplacer a la souris, vous pouvez deplacer un module d'une bibliotheque vers une 
autre, ainsi que le montre la figure 2-8. Dans cet exemple, les deux bibliotheques 
sont dans deux documents differents. 

Bien entendu, la bibliotheque cible ne doit pas deja contenir un module de meme 
nom. En appuyant sur la touche Ctrl, la meme manipulation effectue une copie du 
module (l'icone de transfert affiche un signe +). 

Les boites de dialogue peuvent de meme etre transferees ou dupliquees, avec l'onglet 
BoTtes de dialogue du panneau Gestion de macros. 
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Figure 2-8 

Transfert d'un module 
entre bibliotheques 
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Creer, supprimer un module ou une boite de dialogue 

Pour creer un nouveau module, affichez l'onglet Modules du panneau Gestion des 
macros, puis cliquez sur la bibliotheque qui vous interesse. Cliquez sur le bouton Nou- 
veau module.... Choisissezle nom du module selon vos souhaits. 

Pour creer une nouvelle boite de dialogue, affichez l'onglet BoTtes de dialogue du pan- 
neau Gestion des macros, puis cliquez sur le bouton Nouveau. 

Pour supprimer un module ou une boite de dialogue, cliquez sur cet element pour le 
mettre en evidence, puis cliquez sur le bouton Supprimer. 

Ces operations sont aussi realisables dans la fenetre de l'editeur de macros, que nous 
decrivons plus loin. 



Gerer les macros Basic 

Revenez sur le premier panneau Macro de la figure 2-1. Si la bibliotheque mise en 
evidence dans la partie gauche ne possede pas de module, le bouton Nouveau cree un 
nouveau module dans cette bibliotheque. Si le module mis en evidence dans la partie 
gauche ne possede pas de macro, le bouton Nouveau en cree une dans le module et lui 
donne pour nom Mai n (terme anglais pour Principal). De plus, la fenetre de l'editeur 
de macros s'affiche, montrant cette macro : 

REM ***** BASIC ***** 
Sub Main 
End Sub 
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II s'agit simplement d'une macro vide. Vous pouvez changer le nom de la macro et 
ecrire ce que vous souhaitez. 

Fermez cette fenetre et reaffichez le panneau Macro. La partie droite de celui-ci liste 
les macros qui se trouvent dans le module selectionne a gauche. Remarquez que le 
bouton Nouveau a disparu, remplace par un bouton Supprimer. Cliquez sur une des 
macros pour la selectionner (figure 2-9). 



Figure 2-9 

Panneau Macro avec une 
macro selectionnee 




Le bouton Executer permet de lancer la macro selectionnee. 

Le bouton Assigner... ouvre le panneau du menu Outils>Personnaliser afin de faire 
declencher la macro sur un evenement, sur une entree de menu, sur un raccourci cla- 
vier, ou en declenchant un bouton de barre d'outils. 

Le bouton Supprimer supprime la macro selectionnee. 

Le bouton Editer ouvre la fenetre de l'editeur de macros Basic, que nous allons decou- 
vrir maintenant. 



La fenetre d'edition de macros Basic 

La figure 2-10 presente la fenetre de l'editeur de macros, appele aussi Environnement 
de Developpement Integre, ou EDI. Lordre des barres d'outils peut varier. Cette 
fenetre affiche le contenu du module Modulel de la bibliotheque Standard du docu- 
ment premierEssai .odt. Le curseur d'insertion est sur la ligne 3 colonne 9, c'est une 
barre verticale. Ces informations apparaissent dans la ligne d'etat en bas de la fenetre. 
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Nous voyons aussi un onglet intitule Modulel et des boutons pour se deplacer d'un 
onglet a l'autre. Chaque onglet correspond a un module de la bibliotheque en cours. 
Ici, nous n'avons qu'un seul module. 

Figure 2-10 L IJIJ "J, JH.^ ' , ^[^^MI.H.I.U. ' .lM ' J. fWTTffl^^^^^^^^^M -ln|x| 



La fenetre de I'editeur 
de macros 




Nous verrons plus loin a quoi servent les zones Temoin/variable et Appels. Sachez que 
ces zones sont redimensionnables a l'interieur de la fenetre principale. Si vous 
double- cliquez sur une zone grise d'un panneau tout en maintenant la touche Ctrl 
enfoncee, celui-ci devient flottant ou retourne a sa place. 

Le cceur de la fenetre est une zone d'edition comportant toutes les instructions et les 
commentaires du module. Ici, nous avons une macro creee automatiquement, Mai n, 
precedee d'une ligne commentaire qui rappelle que ce qui suit est du langage Basic. 
Un editeur de texte est similaire a un traitement de texte, excepte qu'on ne peut 
employer aucune mise en forme (gras, italique, souligne, couleurs). 

La coloration syntaxique 

Ce nest pas visible dans ce livre, mais certains mots de la zone d'edition sont 
colores : I'editeur Basic offre la coloration syntaxique, c'est-a-dire qu'il reconnait ins- 
tantanement des mots-cles du Basic et leur affecte une couleur particuliere, sans 
action particuliere de votre part. C'est tres pratique a l'usage car cela permet une pre- 
miere verification du codage. Par exemple, tout commentaire, comme la premiere 
ligne, est reconnaissable. Un commentaire est ignore a 1' execution, done un codage 
de cette couleur ne sera jamais execute (c'est parfois volontaire). Notez que, parfois, 
Basic colore a tort certains mots, car il les reconnait comme des mots reserves, alors 
que dans le contexte leur signification est autre. 
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Si les couleurs proposees vous rendent la lecture difficile, vous pouvez les changer a 
partir du menu Outils>Options>OpenOffice.org>Apparence. Dans la zone Couleurs Person- 
nalisees, utilisez l'ascenseur vers le bas pour voir la section Mise en evidence de la syntaxe 
du Basic. Pour chaque element syntaxique, vous pouvez choisir la couleur a utiliser. 



Ma premiere macro Basic 

La macro de la figure precedente est parfaitement constitute et peut etre executee. 
Seulement, elle ne fait rien de particulier. Nous allons proceder a quelques modifica- 
tions avec l'editeur de macros. 

Remplacez le mot Mai n par un nom de macro plus significatif : Di reBonjour. 
Sur la ligne vide suivante, tapez deux espaces et le texte suivant : 

info = "Bon jour ! " 

Utilisez bien le caractere guillemet (la touche 3 du clavier principal). Au fur et a 
mesure que vous tapez, le texte apparait d'une certaine couleur a partir du premier 
guillemet, puis toute la sequence change de couleur quand vous tapez le guillemet 
final. Ceci est encore un avantage de la coloration syntaxique : elle vous permet de 
verifier que votre chaine de caracteres est correctement ecrite. Nous venons d'affecter 
la chaine de caracteres « Bonjour ! » a la variable info. 

Placez le curseur en bout de ligne et tapez sur la touche Entree. Vous constatez que 
votre curseur se retrouve sur une nouvelle ligne, mais apres deux espaces automati- 
quement inseres. C'est encore une facilite de l'editeur de macro : l'indentation auto- 
matique en fonction de la ligne precedente. Elle produit une sorte de structuration 
des instructions successives, qui facilite la relecture. En Basic, les espaces et tabula- 
tions peuvent etre employes entre des mots sans influence sur 1' execution. Naturelle- 
ment, vous pouvez effacer les espaces si necessaire. Saisissez done cette ligne : 

MsgBox info 

Elle a pour fonction d'afficher un petit panneau contenant notre salutation et un 
bouton OK pour le refermer. L'instruction MsgBox est assez sophistiquee, elle sera 
decrite au chapitre 5. 

Voila, nous avons cree une macro qui vous dit bonjour. II n'y a plus qua l'executer, ce 
qui peut se faire de differentes facons. 
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Executer une macro depuis I'editeur Basic 

Nous avons deja vu une maniere d'executer une macro, avec le panneau Macro. 
Cependant, il est possible d'executer la macro depuis I'editeur ; cela nous ouvrira 
davantage de possibilites. 

Cette macro etant la premiere du module, nous pouvons 1' executer en cliquant sur 
l'icone Executer le programme BASIC (survolez les icones avec la souris pour voir les 
textes des bulles). Le resultat est reproduit a la figure 2-11. 



Figure 2-11 
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Si vous avez bien observe avant de cliquer sur le bouton OK du message, vous avez 
remarque qu'un « voyant rouge » s'est allume sur la barre d'outils. II vous indique 
qu'une macro est en cours d'execution. Dans les cas de bouclage infini (si vous avez 
fait une erreur dans votre programme), vous pourrez arreter l'execution en cliquant 
sur ce voyant, ou en utilisant le raccourci Ctrl + Maj + Q. Dans certains cas malheureu- 
sement, ce ne sera pas possible... 



Aides a la mise au point 

Voir le contenu d'une variable 

Cliquez a la souris sur le mot « info » dans la macro. Ensuite, cliquez sur l'icone 
Activer le temoin, comme indique a la figure2-12. 

Vous venez de demander a I'editeur de vous afficher en permanence la valeur de la 
variable info. On appelle ceci un temoin. L'icone activant le temoin ne sert pas a le 
desactiver, contrairement au texte indique. La deactivation se fait en bas de la 
fenetre, en cliquant sur l'icone Supprimer le temoin. Vous pouvez afficher simultane- 
ment autant de variables que vous le souhaitez. 

Pour le moment, la variable i nf o n'a pas de valeur car la macro ne s'execute pas. 
Laffichage n'apparait que dans un arret temporaire de l'execution de la macro. La 
premiere methode consiste a avancer ligne par ligne dans la macro. II suffit de cliquer 
sur l'icone Etape par etape (ou Step Into). En cherchant cette icone, vous aurez 
remarque deux autres icones similaires dont vous verrez l'utilite a l'usage. Cliquez 
done sur l'icone Etape par etape, une fois, encore une fois, etc. Une fleche jaune en 
marge vous indique la prochaine instruction a executer. Le voyant rouge reste allume, 
car la macro est en cours d'execution. 
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Figure 2-12 

Afficher un temoin 




Observons la zone des temoins. Notre variable info commence par afficher 
<Out of Scope> ce qui veut dire quelle n'est pas significative. Puis, sa valeur s'affiche 
quand la fleche jaune a depasse l'instruction d'affectation. Positionnez la souris au- 
dessus de la variable i nfo, dans le codage : une bulle affiche sa valeur. 

Cliquez encore sur l'icone. Le message s'affiche. Cliquez sur le bouton OK. La fleche 
jaune pointe sur la derniere ligne de la macro, l'execution n'est pas encore terminee. 
Cliquez une derniere fois sur l'icone Etape par etape. 

II est aussi possible de visualiser les proprietes d'une variable objet de l'API. Ces 
objets peuvent etre extremement sophistiques, comme nous le verrons a partir du 
chapitre 7. La figure 2-13 presente un exemple de l'affichage d'un tel objet. Nous 
verrons a 1' annexe A que l'outil Xray permet d'obtenir encore plus d'informations sur 
les objets API. 

Poser des points d'arret 

Maintenant, supposez que votre macro execute 1 000 fois une boucle avant d'arriver a 
l'instruction qui vous interesse. Impossible d'utiliser l'execution instruction par 
instruction ! La solution est d'utiliser un point d'arret. Positionnez votre curseur sur la 
ligne comportant MsgBox. Cliquez sur l'icone (Des)activer le point d'arret. Un rond rouge 
apparait en marge de cette instruction. Cliquez sur l'icone Executer le programme BASIC. 
La macro s'execute et s'arrete avant d'executer l'instruction identifiee par le point 
d'arret. Le voyant rouge est allume, vous pouvez lire la valeur des temoins que vous 
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Figure 2-13 

Afficher un objet de I'API 
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avez poses. Cliquez de nouveau sur l'icone Executer le programme BASIC ou une des 
icones de pas-a-pas : la macro reprend son deroulement jusqu'a la fin. 

Vous pouvez poser plusieurs points d'arret dans un programme, dans plusieurs 
macros ou dans la meme macro. Enlevez un point d'arret en repetant la methode 
employee pour le poser. On peut aussi poser ou enlever un point d'arret par un 
double-clic en marge de l'instruction concernee. 

Verifier la syntaxe 

Une des icones des barres d'outils s'appelle Compiler. En realite, il n'est nul besoin de 
compiler un programme Basic avant de le lancer, car ceci est fait automatiquement 
avant toute execution. Neanmoins, cette commande est utile pour effectuer une veri- 
fication de la syntaxe du module. Par exemple, supprimez la lettre b dans l'instruc- 
tion End Sub de notre macro. Cliquez sur l'icone Compiler ; Basic ronchonne en vous 
affichant un message d'erreur. Si votre programme utilise des macros reparties dans 
plusieurs modules, effectuer une compilation a chaque modification d'un module 
vous evitera des erreurs bizarres et difficiles a trouver. 
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Modules et macros 

On peut changer le nom d'un module en renommant son onglet ; soit par un clic 
droit sur l'onglet, puis Renommer, soit par un Alt + clic sur l'onglet. L'editeur Basic 
affiche les onglets dans l'ordre alphabetique, les modules d'abord, les boites de dia- 
logue ensuite. 

Attention Nom de module 

Ne donnez pas a un module le meme nom que celui d'une macro de la meme bibliotheque. Cela provo- 
querait des anomalies d'execution. 

Un clic droit sur la zone des onglets donne acces a l'insertion d'un nouveau module 
ou d'une nouvelle boite de dialogue. Choisissez Module Basic. Vous obtenez un nouvel 
onglet intitule Module2 et, dans la zone d'edition, toujours la meme macro vide : 

REM ***** BASIC ***** 
Sub Main 
End Sub 

Comme les macros ne sont pas locales a un module mais communes a toute la biblio- 
theque, il est preferable que les macros de la bibliotheque aient des noms tous diffe- 
rents, meme si ce nest pas impose par OOoBasic. Renommez done systematique- 
ment le sempiternel Mai n. 

Par un simple clic sur l'onglet, vous affichez instantanement un des modules de la 
bibliotheque. Repartir les macros dans differents modules facilite leur acces pour 
l'edition et pour 1' execution, car nous avons vu que les icones Executer et Etape par 
etape lancent seulement la premiere macro du module. 

Autres fonctionnalites de l'editeur 

Les icones Selectionner une macro et Selectionner un module ouvrent les panneaux que 
nous avons deja decrits. L'icone Enregistrer BASIC sous... ecrit un fichier contenant le 
texte du module. Ce fichier possede l'extension bas. A l'inverse, l'icone Inserer le texte 
source BASIC insere dans le module en cours le contenu d'un fichier d'extension bas. 

II arrive qu'une ligne d'instruction ou de commentaire soit plus grande que la zone 
d'affichage. L'ascenseur horizontal se trouve en dessous de la zone Appels. 

Sur un arret d'execution, la zone Appels, en bas a droite de la fenetre, affiche la pile 
des appels successifs de macros. En effet, un programme est decompose en nom- 
breuses macros, qui s'appellent l'une 1' autre en cascade. 
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Les zones Temoin et Appels sont redimensionnables dans la fenetre. Un Ctrl + double 
die sur une partie grisee de ces zones les fait flotter, ce qui permet de degager la zone 
d'edition. La meme manipulation les fait reintegrer la fenetre. 



Introduction a la programmation Basic 

Avec cette section, vous debutez l'apprentissage du Basic OpenOffice.org. Vous ferez 
connaissance avec les regies de syntaxe du langage et nous vous donnerons quelques 
conseils de bonne programmation. 

Remarque Debutants 

Ne soyez pas rebute par les termes employes dans les lignes de code reproduites ici. lis seront expliques 
progressivement dans les chapitres suivants. Pour le moment, ecrivez-les exactement comme ecrit. 



Les elements de base 

Nous vous recommandons de poser votre livre sur la table de votre ordinateur et 
d'ouvrir l'EDI sur un nouveau module. N'hesitez pas a mettre en application imme- 
diate ce que nous allons exposer. Vous avez done probablement devant vous une page 
Basic ecrite ainsi : 

REM ***** BASIC ***** 
Sub Main 
End Sub 

Comme nous l'avons deja vu, cette page contient : 

• une ligne de commentaire, commencant par REM ; 

• une macro nommee Main. 

Cette description nest pas complete. Nous avons en plus des lignes vides (ou lignes 
blanches) et des espaces entre les mots-cles. 

Premier point important : un programme Basic est compose de lignes. Cela peut 
paraitre une evidence sans interet, mais cette phrase veut dire que Basic utilise la 
decoupe en lignes pour « comprendre » ce qu'on lui demande de faire. Ainsi, les 
termes Sub Mai n et End Sub doivent etre sur deux lignes differentes et dans cet ordre. 

Un module Basic comporte au maximum environ 65 000 caracteres. Attention, cer- 
tains codes provenant de macros VBA de MS-Office depassent cette limite et 
devront etre scindes en plusieurs modules pour eviter des anomalies dans l'EDI. La 
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decoupe est simple si le module initial comporte plusieurs routines : il suffit d'en 
deplacer certaines dans un ou plusieurs autres modules de la meme bibliotheque, elle 
restent toutes accessibles. Si le module VBA ne comporte qu'une seule routine de 
plus de 65 000 caracteres, il s'agit d'un programme particulierement mal ecrit, autant 
le repenser completement ! 

Les elements non interprets 

Certaines parties du codage ne sont jamais utilisees par Basic. Elles servent seule- 
ment a un lecteur humain. 

Les espaces et tabulations 

Basic permet d'employer un nombre quelconque d'espaces ou de tabulations sur 
chaque ligne de code. Ceci n'aura pas d'influence sur la vitesse d'execution des 
macros. Basic ne considere ces elements que comme separateurs entre deux mots, ou 
a l'interieur d'une chaine de caracteres. Ceci lui est done tout a fait equivalent : 

REM ***** BASIC ***** 

Sub Main 

End Sub 

Contrairement a cet exemple, en utilisant judicieusement des espaces, vous pouvez 
simplifier considerablement la relecture de vos programmes en mettant en evidence 
leur structure. 

Les commentaires 

Les commentaires debutent par le mot-cle REM. A partir de ce mot, Basic ignore 
completement le reste de la ligne. Vous pouvez y mettre un texte quelconque, y com- 
pris avec des caracteres accentues. Le caractere apostrophe ' (la touche 4 sur le clavier 
principal) remplit la meme fonction que le mot-cle REM. Voici plusieurs exemples de 
commentaires, que nous reproduisons en gris clair dans ce livre : 

REM ***** BASIC ***** 

rem Code02-01.odt bibli : Standard Modulel 
Sub Main ' une macro appelee Main 

'MsgBox "Bonjour" 
End Sub REM fin de la macro Main 

Basic ne distingue pas les majuscules des minuscules pour les mots-cles et les noms 
de variables. Ainsi nous avons employe REM et rem pour les commentaires. 
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ASTUCE Les exemples du livre 

Les exemples complets du livre sont deja ecrits dans des documents Writer, Calc, Draw que vous trouve- 
rez dans le Zip telechargeable disponible sur le site de I'editeur (www.editions-eyrolles.com). 
Copiez le document sur votre disque dur et ouvrez dans I'EDI le module de la bibliotheque indiquee dans 
la ligne rem Codexx-yy. 



Longueur des lignes 

Basic accepte les lignes de tres grande longueur. Neanmoins, comme I'editeur 
n'affiche qu'une zone limitee, faites attention aux mots qui pourraient se cacher der- 
riere une sequence d'espaces ou tabulations. 

Un livre ne peut malheureusement pas representer de longues lignes de codage. Aussi 
nous serons contraints de couper certaines lignes trop longues. Nous emploierons 
alors le caractere « souligne » _ (la touche 8 du clavier principal), qui est reconnu par 
Basic comme indiquant que la meme instruction se poursuit sur la ligne suivante. Ce 
caractere doit etre le dernier de la ligne, on ne peut mettre ni espace ni commentaire 
a sa droite ; il ne doit pas couper un mot ni etre accole a lui. 

rem Code02-01.odt bibli : Standard Modulel 

Sub Macrol ' un peu de poesie dans ce monde i nformatique 
MsgBox("La tout n'est qu'ordre et beaute," & chr(13) & _ 
"Luxe, calme et volupte." & chr(13) & _ 

Charles Beaudel ai re") 

End Sub 



A NOTER Commentaires et chaines de caracteres 

Le seul moyen de continuer un commentaire sur plusieurs lignes est de repeter le REM ou I'apostrophe a 
chaque ligne. Le caractere de continuation est traite comme un caractere ordinaire a I'interieur d'une 
chame de caracteres. 



Instructions Basic 

Les instructions Basic simples s'ecrivent sur une seule ligne. II est possible de mettre 
plusieurs instructions Basic sur la meme ligne en les separant par le caractere deux 
points : . Toutefois, evitez ce style d'ecriture car vous auriez plus de difficulte a relire 
vos programmes. 

D'autres instructions s'ecrivent obligatoirement sur plusieurs lignes, comme 
Sub . . . End Sub. 

Basic est un langage de programmation de langue anglaise. Les mots-cles qui le 
composent sont des mots anglais (meme si certains sont aussi des mots francais 
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comme Date, Envi ron, Mi nute). II en est de meme des noms employes par l'API, que 
nous utiliserons a partir du chapitre 7. 

Noms des variables et des routines 

Un programmeur utilise de nombreuses routines (sous-programmes), variables ou 
constantes. II les designe chacune par un nom particulier. 

Basic est indifferent a la casse des caracteres, c'est-a-dire qu'il ne distingue pas un 
caractere alphabetique en minuscule du meme caractere en majuscule (nous nuance- 
rons cependant ceci quand nous aborderons l'utilisation des constantes nominees de 
l'API). De plus, les noms doivent respecter les regies suivantes : 

• comporter entre 1 et 255 caracteres ; 

• le premier caractere doit etre alphabetique (une des 26 lettres de 1' alphabet, 
majuscule ou minuscule mais non accentuee), ou bien etre le caractere souligne _ 
a condition qu'il soit suivi d'au moins un autre caractere alphabetique, numerique 
(0 a 9) ou souligne ; 

• les caracteres suivants sont alphabetiques, numeriques ou le caractere souligne ; 
evitez de terminer le nom par un souligne. 

Basic accepte, sous certaines conditions precisees dans l'aide en ligne, des caracteres 
espace dans un nom. Nous deconseillons cet usage. 

Les caracteres alphabetiques accentues ou les caracteres speciaux sont interdits dans 
un nom. Cette limitation sera partiellement levee dans une version future. Certains 
caracteres comme $ et % sont utilises dans les noms, mais pour des usages particuliers 
que nous expliquerons au chapitre 3. 

Syntaxe elementaire 

L'affectation d'une valeur a une variable s'ecrit simplement avec le signe egal : 
unCompteur = 3 

La partie a droite du signe egal peut comporter un simple nombre ou une autre 
variable, mais peut aussi bien etre une expression assez complexe : 

unCompteur = unCompteur + comptesC"lient(numC"lient) 

Les macros et beaucoup d'instructions Basic peuvent comporter des parametres en 
argument, ou aucun argument. En principe, les arguments sont encadres de paren- 
theses comme ici : 

MsgBox("Le travail est termine", messlnfo, ti treFenetre) 



Introduction au Basic I 

Chapitre 2 I 

Basic accepte, dans une instruction aussi simple, d'omettre les parentheses : 
MsgBox "Le travail est termine", messlnfo, titreFenetre 

En revanche, si la macro ou instruction est un element d'une expression plus ela- 
boree, les parentheses sont necessaires. En cas de doute, utilisez-les. 

Dans le cas particulier d'une macro ou instruction Basic hutilisant aucun argument, 
les deux formes suivantes sont done possibles : 

macrolO 
macrol 

Ces deux formes sont autorisees dans toutes les constructions. 
Attention Parentheses 

Les parentheses jouent un role different pour les variables. Une variable change de signification avec ou 
sans parentheses. Voir le chapitre 3. 

Certaines macros et instructions Basic peuvent renvoyer une valeur resultat ; on les 
appelle des fonctions. Le resultat de la fonction peut etre volontairement ignore. 

rem Code02-01 . odt bibli : Standard Module2 
Sub Main2 

print Time ' la valeur renvoyee est affichee 
Time ' la valeur renvoyee est ignoree 
End Sub 

En fait, ici la deuxieme ligne ne sert a rien. Cela pourrait etre une erreur de program- 
mation, et Basic ne produira aucun message d'erreur. 

Execution Basic 

En principe, vous ne pouvez realiser qu'une seule execution Basic a la fois. Avec un 
ecran d'ordinateur submerge de fenetres, on peut avoir oublie qu'un programme 
Basic est en cours d'execution, stoppe a un point d'arret. Or, beaucoup de petits 
ajouts bien pratiques sont realises avec des macros Basic. Le declenchement d'une 
macro Basic a partir d'une icone de barre d'outils dans un document OpenOffice.org 
peut alors donner des resultats bizarres. 

Tant que Basic est en cours d'execution, OpenOffice.org ne vous permet pas de 
fermer le document qui a lance la macro. 
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Recommandations de programmation 

Comme indique dans ce titre, nous vous presentons ici des recommandations. Vous 
n'etes pas oblige de les suivre, ni d'etre d'accord. Elles sont cependant acceptees par 
bien des professionnels. 

Certaines des recommandations delivrees ici concernent des concepts que nous abor- 
derons plus loin dans ce livre. Aussi n'hesitez pas a les relire de temps en temps. 
Toutes ont le meme but : vous aider a ecrire des programmes clairs, maintenables 
(c'est-a-dire qui peuvent etre modifies longtemps apres, meme par une autre per- 
sonnel et moins sujets aux erreurs. 

Le choix des mots 

Entre 1 et 255 caracteres, il y a place pour des noms de variables et de routines d'une 
longueur raisonnable. Le programme ne sera pas ralenti avec des noms de grande 
longueur. En revanche, il sera plus difficile a relire et a mettre au point si les noms 
sont trop courts ou trop longs. 

Dans la mesure ou vous n'etes pas contraint par des regies de nommage propres a 
votre entreprise, choisissez pour vos noms de variables et macros des noms significa- 
tifs de leur utilite, et ecrits en minuscules, sauf pour mieux reperer des mots lorsque 
ce nom est une concatenation de mots. Voici des exemples de variables : 

monDocument , numeroCl i ent , coul eurCadre 

Une macro Sub effectue une action ; choisissez comme nom un verbe a l'infinitif qui 
decrit Faction : 

imprimerRapportO 

Pour une macro renvoyant une valeur booleenne (vrai, faux), choisissez un nom qui 
se combine avec l'instruction i f pour rappeler la signification d'un resultat ayant la 
valeur vrai : 

if clientExiste(nomClient) then 

En employant de tels noms, votre codage deviendra « auto-documente », c'est-a-dire 
qua la lecture des instructions, vous aurez deja une bonne idee du traitement realise. 
Ceci ne vous dispense pas pour autant de commenter les sequences complexes. 

Pour eviter des erreurs sur le nom des variables et routines, utilisez systematiquement 
le copier-coller (ou Ctrl + glisser-deplacer avec la souris). 

Inversement, pour des variables « de travail » a usage tres localise, par exemple un 
simple index dans une boucle, il est plus lisible d'utiliser une variable a un ou deux 
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caracteres. Evitez les variables a un caractere dont la graphie ressemble a un chiffre 
(lettres i, 1, o). Preferez les variables comme x, x2, n, p3, aa. 

Certains d'entre vous peuvent avoir besoin de programmer en langue anglaise. 
Mefiez-vous des noms de variables anglais, vous risquez des collisions avec des noms 
reserves ou des noms utilises par l'API OpenOffice.org. Un bon moyen d'eviter ces 
problemes est de mettre un ou plusieurs chiffres dans le nom. 

N'hesitez pas non plus a changer le nom d'une variable ou d'une macro si cela peut 
clarifier le codage. L'EDI vous permet de faire un chercher-remplacer sur une zone 
selectionnee aussi bien que dans tous les modules de la bibliotheque. 

Les noms de modules devraient aussi etre significatifs, mais des noms longs rendent 
les onglets difficiles a manipuler. Ne choisissez pas comme nom de module le nom 
d'une des macros de celle-ci. 

Choisissez bien le nom de vos bibliotheques, afin d'eviter que ce nom soit susceptible 
d'etre aussi choisi par un autre programmeur pour sa propre bibliotheque. 

La forme : commentaires et espaces 

Utilisez les lignes vides et les espaces (ou les tabulations) pour aerer votre codage et 
mettre en valeur certaines structures. Cela ne prend pas beaucoup plus de temps a 
ecrire et vous aidera grandement dans vos relectures. 

Ajoutez des commentaires, la ou c'est utile, avec un texte clair et concis. Supposez 
que votre programme doive etre modifie par un autre programmeur de competence 
moyenne, ou que vous ayez a le modifier cinq ans apres l'avoir termine. Ne com- 
mentez cependant pas les codages simples et evidents, voyez ce qui est dit a propos 
du choix des noms. 

Modularity 

Decoupez votre programme en multiples macros. Idealement, chaque macro devrait 
etre entierement visible dans la fenetre d'edition de l'EDI. Ceci implique d'appeler des 
macros en cascade. Chaque macro devrait realiser une tache clairement delimitee. 

Evitez les variables globales (voir chapitre 3) et preferez les variables locales a une 
macro ; transferez les informations dans des parametres de macro. 

Autant que possible, testez chaque macro separement, en commencant par celles qui 
n'en appellent aucune autre. Si vous ne comprenez pas pourquoi votre macro fonc- 
tionne mal, simplifiez-la jusqu'a trouver la raison du probleme. 

On peut regrouper dans un meme module les macros concourant a la realisation 
d'une tache complexe. La decoupe en plusieurs modules permet de passer facilement 
d'une partie a une autre du programme. 
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Servez-vous des codages deja realises comme base pour vos nouvelles macros. Uti- 
lisez abondamment le copier-coller puis adaptez a vos besoins. 

Ne re-inventez pas la roue a chaque nouveau programme ! Avec 1' experience et en vous 
basant sur des codages existants, vous deviendrez capable de creer des macros generi- 
ques qui, une fois ecrites et testees, seront reutilisables sans modifications et pourront 
etre considerees comme des super-instructions Basic. Cette approche, si vous deve- 
loppez beaucoup de macros, vous fera gagner un temps precieux et vous pourrez ainsi 
vous concentrer sur la finalite de la macro que vous etes en train de developper. 

Simplicity 

II y a en general une infinite de manieres de resoudre un probleme par un pro- 
gramme. Preferez les solutions simples et robustes aux solutions astucieuses mais peu 
evidentes. Reprenez plusieurs fois votre codage, car la premiere solution est rarement 
une solution simple. 

La simplicite resulte aussi d'une parfaite comprehension du sujet a traiter, et d'une 
bonne connaissance des possibilites de votre langage de programmation. Vous ne les 
acquerrez qu'avec le temps et la pratique. 

Robustesse 

Evitez de mettre un nombre ou une chaine de caracteres directement dans une ins- 
truction, si cette chaine ou ce nombre est employe plusieurs fois ou est susceptible 
d'evoluer dans le futur, ou a une signification particuliere. Utilisez une constante ou 
une variable a la place et initialisez-la a un endroit bien visible : 

rem Code02-01.odt bibli : Standard Module3 
Sub Main 3 

Const titreFenetre = "Ma jolie macro" 

Const messlnfo = 64 ' valeur indi quant le type du message 

' - - - ici les "instructions de la macro - - - 

MsgBox("Le travail est termine", messlnfo, titreFenetre) 
End Sub 

Chaque fois que vous devez recevoir une valeur provenant de l'utilisateur, ou de la 
lecture d'un fichier, attendez-vous au pire. C'est-a-dire, avant de commencer tout 
traitement, verifiez par votre codage que la donnee obtenue est bien dans la gamme 
des valeurs autorisees. Si plusieurs donnees doivent etre recueillies, verifiez la cohe- 
rence entre elles. 
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Relectures 

L'ordinateur n'a aucune intelligence ; il ne fait que ce que vous lui dites de faire, et il le fait 
aveuglement. La moindre erreur peut rendre votre superbe construction totalement inuti- 
lisable. Or, les etres humains sont faillibles, et malgre toute la concentration que vous 
apporterez, malgre votre experience, vous ferez des erreurs, parfois difficiles a trouver. 

Ne vous dites pas : je mettrai tout 9a au point avec les tests. En realite, aucune serie 
de tests ne peut garantir le bon fonctionnement d'un programme un peu complexe. 
Elle peut seulement demontrer que le programme ne marche pas. De plus, definir un 
ensemble de tests efficace est un travail aussi complexe que d'ecrire un programme. 

N'hesitez done pas a relire et relire encore vos codages de maniere critique, de prefe- 
rence apres quelques jours. Avancez pas-a-pas dans votre lecture en vous posant des 
questions comme : la variable est-elle bien initialisee ? L'appel de cette instruction 
est-il correct ? Ai-je bien verifie toutes les branches d'execution de cette macro ? Ce 
codage ne pourrait-il pas etre simplifie ? 



Conclusion 

OooBasic est un langage a part entiere permettant d'exploiter l'API d'OpenOffice.org. 
Sa portee s'etend sur toutes les fonctionnalites qu'offre une suite bureautique. II permet 
d'automatiser certaines taches mais egalement de creer de nouvelles fonctionnalites en 
rearrangeant et en utilisant les briques logicielles mises a sa disposition. 

OpenOffice.org fournit un environnement de developpement complet permettant de 
gagner du temps dans la mise au point des macros Basic. Coloration syntaxique, 
debogage... sont autant d'outils indispensables pour creer ses macros dans de bonnes 
conditions. Les macros sont classees et hierarchisees en bibliotheques et modules, ce 
qui permet de rationaliser le developpement. 

Nous avons presente le cadre syntaxique general de OooBasic. Les conseils qui ont 
ete donnes en termes d'habitudes d'ecriture permettront d'ecrire des macros claires et 
documentees. Ce ne pourra etre que benefique par la suite. 

Nous pouvons maintenant aborder les variables et types de donnees, briques de bases 
essentielles a la programmation. 
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Variables et 
tableaux de variables 



Qu'est-ce qu'une variable ? C'est une zone de memoire volatile a laquelle on donne un 
nom, et qui sert a memoriser une information. Memoire volatile veut dire que celle-ci 
ne se conserve pas si on coupe l'alimentation de l'ordinateur. Basic dispose de differents 
types de variables, pour differents usages. Nous allons les decrire dans ce chapitre. 

Declarer des variables 

Le programmeur declare une variable pour prevenir l'ordinateur qu'il doit reserver 
une zone memoire et lui donner un nom. 

OpenOffice.org Basic n' oblige pas a declarer les variables simples. Ainsi, le code sui- 
vant utilise une variable nommee Chanson. 

rem Code03-01 . odt bibli : Libraryl Modulel 

Sub SansDecl arati on() 
Chanson = "Au clair de la Lune" 
print Chanson 
End Sub 
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Ceci est tres pratique, mais a deconseiller, car une simple faute de frappe peut creer 
involontairement des variables. Le code suivant en montre une consequence : 

rem Code03-01.odt bibli : Libraryl Module2 

Sub ErreurFrappe() 

Chanson = "Au clair de la Lune" 

1 supposons toute une serie d ' i nstructi ons ici 

i 

Chason = "II pleut Bergere" 

i 

' supposons toute une serie d ' i nstructi ons ici 

print Chanson 
End Sub 

En executant cette macro vous verrez le message : « Au clair de la Lune », au lieu de 
« II pleut Bergere ». 

Vous avez fait une petite faute de frappe et votre programme fonctionne d'une autre 
maniere, mais sans aucune erreur. Sachant que dans des applications complexes, vous 
pouvez avoir besoin de plusieurs dizaines de variables utilisees chacune plusieurs fois, 
mesurez les risques que vous prenez. 

La declaration Explicit 

Pour eviter ces erreurs, Basic dispose d'une declaration optionnelle : 
Option Explicit 

Cette ligne doit etre ecrite au debut du module, avant toute instruction. Elle peut 
etre precedee de commentaires, d'espaces, ou de lignes blanches. Apres cette declara- 
tion, toute variable utilisee doit etre declaree par une instruction Di m avant de l'uti- 
liser ou de l'initialiser. Modifions le code precedent, qui devient : 

rem Code03-01.odt bibli : Libraryl Module3 
Option Explicit 

Sub DeclarationObligatoireO 
Dim Chanson As String 

Chanson = "Au clair de la Lune" 

1 supposons toute une serie d ' i nstructi ons ici 



Variables et tableaux de variables 

Chapitre 3 



Chason = "IT pleut Bergere" 
i 

' supposons toute une serie d ' i nstructi ons ici 
i 

print Chanson 
End Sub 

Si vous executez cette macro, Basic affichera un message d'erreur (figure 3-1). 



Figure 3-1 

Erreur d'execution 



em Code05-01.odt bibli : Libraryl Hodule3 
tption Explicit 

Sub DeclarationObligatoire () 
Dim Chanson As String 

anson = "Au clair de la Lune" 



instructions ici 




Non seulement Basic vous previent d'une anomalie, mais il ouvre l'EDI si necessaire 
et selectionne la ligne en faute ! Vous obtiendriez le meme message si l'erreur de 
frappe se situait non pas ici, mais a l'instruction pri nt. 

Si la declaration Dim n'existait pas, Basic afficherait une erreur des la premiere ins- 
truction d'affectation. En effet, Dim sert a declarer a Basic les variables que nous vou- 
lons utiliser. 

La declaration Dim 

Nous venons de voir une forme tres courante de la declaration Di m. 
Dim Chanson As String 

Elle signifie : je declare que la variable Chanson est du type String. Nous verrons 
plus loin ce quest le type String. Le mot reserve As doit preceder le type de la 
variable. 

II existe une forme plus simple : 
Dim Chanson 



Le langage OOoBasic 

Deuxieme partie 

Pour Basic, cette forme est equivalente a : 
Dim Chanson As Variant 

Vari ant est un autre type de variable, utilise par defaut, que nous decrirons plus loin. 
II est nettement preferable de toujours declarer explicitement le type Variant (et de 
l'employer seulement a bon escient). 

On peut, soit declarer chaque variable avec une declaration Dim, soit les regrouper 
dans une meme declaration : 

Dim Chanson As String, Chanteur As String, Annee As Integer 

Meme si les variables sont du meme type, vous devez repeter le As ... pour cha- 
cune. En effet, l'instruction suivante est acceptee mais signifie autre chose : 

Dim Chanson, Chanteur As String, Annee As Integer 

Elle signifie que la variable Chanson est du type Vari ant puisque vous n'avez pas pre- 
cise le type. II existe d'autres formes de declarations Dim, employees pour les 
tableaux ; elles sont decrites plus loin dans une section specifique. 

Valeur initiale des variables 

Basic donne une valeur initiale a chacune de vos variables. La valeur exacte depend du 
type de la variable ; par exemple, elle equivaut a zero pour les variables numeriques. 

Vous ne devriez pas compter sur Basic pour initialiser vos variables ; prenez plutot la 
peine de le faire vous-meme. Vous deciderez ainsi a quel endroit le faire (parfois il 
faut reinitialiser en cours de traitement), et quelle valeur donner (parfois une valeur 
autre que zero est preferable). 

L'interet de l'initialisation des variables par Basic est que, si vous avez oublie d'initia- 
liser une variable, votre programme se comportera de maniere reproductible, ce qui 
facilite la recherche des erreurs de programmation. Alors que dans d'autres langages, 
une variable non initialisee par le programmeur peut dependre des traces laissees en 
memoire par les applications precedemment executees. 

Contrairement a VBA, il n'est pas possible d'initialiser une variable dans sa declara- 
tion Di m. 
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Portee des variables 

Les variables declarees dans une routine Sub ou Function sont connues seulement 
dans cette routine. Plus exactement, les variables sont connues a l'interieur de la rou- 
tine a partir du moment ou elles sont declarees. II n'est pas obligatoire de regrouper 
toutes les declarations en debut de routine, il suffit de declarer la variable juste avant 
la premiere utilisation. Neanmoins, les declarations au fil de l'eau aboutissent a un 
code moins lisible que des declarations regroupees en un ou deux endroits. 

Puisque les variables d'une routine ne sont pas connues a l'exterieur de celle-ci, il est 
possible de reprendre les memes noms dans differentes routines. 

A l'inverse, il est possible de definir des variables communes a plusieurs routines. Les pro- 
grammeurs experimentes evitent cela autant que possible car la mise au point est rendue 
plus delicate, mais c'est parfois absolument necessaire. Plusieurs cas se presentent. 

Variable commune a un module 

Dans le code qui suit, la routine principale MainlO affecte une valeur a la variable 
Chanson, appelle la routine ModifierChansonO et affiche le contenu de la variable. 

rem Code03-01.odt bibli : Library2 Modulel 
Option Explicit 

Private Chanson As String 

Sub MainlO 

Chanson = "Au clair de la Lune" 
Modi f i erChanson () 
print Chanson 
End Sub 

Sub ModifierChansonO 
Chanson = "II pleut Bergere" 
End Sub 

La declaration Di m est remplacee par une declaration Pri vate, en dehors des deux rou- 
tines mais dans le meme module. Private s'emploie avec la meme syntaxe que Dim. 

L execution de la routine Mai nl() montre que la variable est bien accessible depuis les 
deux routines. En realite, par suite d'un ancien bogue, elle est aussi accessible depuis 
un autre module de la bibliotheque, comme avec la declaration Public que nous 
allons voir ci-dessous. Pour que Private limite la portee de la variable au module, il 
faut utiliser le mode de compatibilite VBA, que nous n'utilisons pas pour les raisons 
exposees au chapitre 2. Utilisez cependant la declaration Private, vous indiquez 
ainsi au lecteur que la donnee ne devrait pas etre utilisee ailleurs que dans ce module. 
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Variable commune a une bibliotheque 

Nous allons declarer une variable dans un module et l'utiliser dans un autre module 
de la meme bibliotheque. Void le module declarant une variable commune : 

rem Code03-01.odt bibli : Library3 Module2 
Option Explicit 

Public Chanson As String 

Sub ModifierChansonO 
Chanson = "II pleut Bergere" 
End Sub 

La declaration Publ i c s'emploie avec la meme syntaxe que la declaration Di m. 

Dans un autre module de la meme bibliotheque, nous placons la routine principale, 
qui affecte une valeur a la variable commune, appelle une routine qui se trouve dans 
l'autre module, et affiche le contenu de la variable : 

rem Code03-01.odt bibli : Library3 Modulel 
Option Explicit 

Sub MainlbisO 

Chanson = "Au clair de la Lune" 
Modi f i erChanson () 
print Chanson 
End Sub 



Variable commune a plusieurs bibliotheques 

Nous allons declarer une variable dans un module d'une bibliotheque. 

rem Code03-02 . odt bibli : Libraryl Modulel 
Option Explicit 

Global Compositeur As String, Naissance As Integer 

Sub AffecterClobal () 
Compositeur = "Vivaldi" 
Naissance = 1678 
End Sub 

La declaration Gl obal s'emploie avec la meme syntaxe que la declaration Di m. 
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Dans une autre bibliotheque du meme document, utilisons cette variable : 

rem Code03-02 . odt bibli : Library2 Modulel 
Option Explicit 

Sub UtiliserGlobal () 

print Compositeur, Naissance 

End Sub 

A condition que la bibliotheque Library2 soit chargee, l'execution de 
UtiliserGlobal () se fera sans erreur. Si AffecterGlobal () a ete executee aupara- 
vant, le resultat affiche sera « Vivaldi 1678». La variable ainsi definie n'est connue 
que dans les bibliotheques du meme document. Si elle est definie dans une des 
bibliotheques de sof f i ce, elle sera connue dans les autres bibliotheques de sof f i ce. 

Dans la bibliotheque ou une variable Global est declaree, la declaration est equiva- 
lente a Public, c'est-a-dire quelle est connue de tous les modules. 

Les variables Global sont persistantes 

Quand la macro se termine, les variables Global memorisent la derniere valeur 
affectee lors du traitement. Si vous relancez la macro, ou une autre macro les utili- 
sant, ne comptez pas sur Basic pour les reinitialiser. Vous devez en tenir compte dans 
vos traitements. La memorisation disparait si le document contenant la declaration 
de ces variables est ferme. Si la declaration se trouve dans Mes macros, la variable res- 
tera memorisee tant que l'application OpenOffice fonctionne. 

Dans certains cas, cette faculte de persistance est indispensable. Mais, en general, 
evitez les variables Global, car mal employees, elles rendent un programme plus 
complexe a mettre au point. 



Les chaTnes de caracteres 

Les variables de type String sont appelees chaines de caracteres. Elles contiennent 
une serie de 0 a 65 535 caracteres, appelee plus communement texte. Chaque carac- 
tere est encode en Unicode a 16 bits, ce qui permet de supporter les caracteres natio- 
naux de nombreuses langues. La chaine de caracteres est construite en encadrant le 
texte de guillemets : 

Chanson = "Au clair de la Lune" 
Tous les espaces sont significatifs a l'interieur de la sequence encadree par les guillemets. 
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Une chaine avec aucun caractere est une chaine de longueur nulle, qui s'ecrit ainsi : 
Chanson = "" 

Basic initialise les variables Stri ng a une chaine de longueur nulle. 

Une chaine de caracteres peut comporter des caracteres guillemets. Chacun de ceux- 
ci doit alors etre duplique. L'EDI facilite l'ecriture de telles chaines grace a sa colora- 
tion syntaxique. 

a = "Je vous dis : ""Bonjour! 



Pour les experts Le type Caractere 

OpenOffice.org Basic ne possede pas de type Caractere. On memorise un caractere avec une chaine a un 
caractere. 

Concatenation 

L'operateur de concatenation & sert a fusionner deux chaines de caracteres. 

rem Code03-03 .odt bibli : Libraryl Module2 
Option Explicit 

Sub Abouter() 

Dim Textel As String, Texte2 As String 
Dim Resultat As String 

Textel = "Le temps" 
Texte2 = "beau" 

Resultat = Textel & " est " & Texte2 
print Resultat 

Resultat = Resultat & " et chaud" 
print Resultat 
End Sub 

L'operateur + est aussi accepte a la place de l'operateur & . Cependant, ce dernier est 
preferable pour eviter les ambiguites de code, notamment lors de l'utilisation du type 
variant. De nombreuses autres operations sont possibles avec les chaines de carac- 
teres, en utilisant les fonctions integrees de Basic decrites au chapitre 5. 
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Les variables numeriques 

OpenOffice.org Basic dispose de plusieurs types de donnees pour representer des 
nombres. II est necessaire de connaitre leurs specificites pour bien les utiliser. 

Les entiers 

II existe trois types de variables numeriques pouvant contenir des nombres entiers, 
voir le tableau 3-1. 



Tableau 3-1 Les types entiers 



Type Gamme des valeurs Occupation memoire 


Byte 


Oa+255 


1 octet = 8 bits 


Integer 


-32 768 a +32 767 


2 octets = 16 bits 


Long 


-2 147 483 648 a +2 147 483 647 


4 octets = 32 bits 



Pourquoi ces bornes bizarres ? Parce que les variables sont stockees sous forme 
binaire. 

Pourquoi trois types ? Historiquement, les types Integer et Long etaient justifies par 
l'occupation memoire, et par la duree des calculs. Aujourd'hui, les capacites memoire 
et la vitesse des processeurs actuels rendent ces criteres obsoletes. Le type Byte a ete 
introduit recemment pour permettre l'utilisation de certaines methodes de l'API. En 
pratique, pour vos variables, entieres utilisez le type Long, d'une part parce que c'est 
moins long a ecrire, et d'autre part parce que cela evite les problemes lies a des valeurs 
un peu grandes. 

En Basic, les nombres entiers (et les autres nombres) sont ecrits sans employer de 
caractere d'espacement de milliers. 

Dim grand As Long 
grand = 123456789 

Basic initialise les variables Byte, Integer et Long a la valeur zero. 

Parmi les operateurs mathematiques pour les variables entieres (voir le tableau 3-4), 
on trouve la division arrondie et la division entiere. Cet exemple montre le resultat 
pour chacune. 

rem Code03-03 . odt bibli : Libraryl Modulel 
Option Explicit 
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I Sub DivEntiersO 

Dim a As Long, b As Long, c As Long, d As Long 

a = 57 
b = 6 

c = a / b ' le resultat de la division est arrondi 
d = a \ b ' division entiere 
print c, d 
End Sub 

Lexecution de la routine donne 10 pour c et 9 pour d. 

Les nombres reels 

II existe deux types de variables numeriques pouvant contenir des nombres a virgule 
flottante, voir le tableau 3-2. 



Tableau 3-2 Les types reels 





Gamme des valeurs non nulles 


Precision 


Occupation memoire 


Single 


± 3,402823 x 10 38 
a 

±1,401298 x10" 45 


6 a 7 chiffres 


4 octets = 32 bits 








Double 


±1,79769313486232 10 308 
a 

±4,94065645841247 10" 324 


14 a 15 ch iff res 


8 octets = 64 bits 









Ces types sont des approximations des nombres reels, avec une precision plus grande 
pour le type Doubl e. Pourquoi deux types ? Historiquement, ils etaient justifies par le 
cout de la memoire et la lenteur des calculs en Double. Aujourd'hui, ces criteres sont 
obsoletes, il est preferable de n'utiliser que le type Double. 

Les nombres en virgule flottante sont ecrits en Basic sans separateur de milliers, avec 
un point pour marquer la decimale, et la lettre E ou e pour marquer le debut de 
l'exposant : 

Dim e As Double, h As Double 
e = 2.718281828459045 
h = 6.625e-34 

Notez que, dans la troisieme ligne, le e annonce l'exposant ; ce nest pas la variable e ! 
Cet exposant represente une puissance de 10, il n'a rien a voir avec l'exponentielle. 
La valeur de l'exposant est obligatoirement un entier. 

Basic initialise les variables Si ngl e et Doubl e a la valeur zero. 
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Les operateurs mathematiques des types reels sont listes au tableau 3-3. Utilisez le 
symbole puissance a pour effectuer des calculs comme les racines « niemes » : 



v = 27A(l/3) ' racine cubique de 27 

Basic fournit des fonctions numeriques et trigonometriques pour les calculs en vir- 
gule flottante. Nous les verrons au chapitre 5. 

Les inconvenients du calcul en flottant 

Les variables reelles sont stockees sous forme binaire flottant. Nous ecrivons et lisons 
les nombres reels dans une representation decimale flottante, et l'ordinateur doit 
done faire une conversion pour les memoriser et realiser ses calculs. Cette conversion 
peut entrainer des petites erreurs, qui peuvent apparaitre visiblement dans un 
resultat. 

Dim a As Single, b As Single, c As Single 

a = 5.777 

b = 5.778 

c = (b-a)-lOOO 

print c ' on devrait afficher la valeur : 1 

Le codage ci-dessus affiche la valeur 0,9999275 ! Avec des variables de type Double, 
le resultat est 1,00000000000122, ce qui nest pas non plus satisfaisant. 

A cause de ces limitations, il ne faut jamais tester l'egalite de deux variables a virgule 
flottante, mais plutot tester si la valeur absolue de la difference est suffisamment 
faible. Le codage suivant presente un cas typique : 

rem Code03-03 . odt bibli : Library2 Modulel 
Option Explicit 

Sub CalculsFlottants() 

Dim A As Double, B As Double, C As Double 
Dim Rl As Double, R2 As Double 

A = -1.2345 
B = 1.2346 
C = -0.0001 
Rl = B + A + C 
R2 = B + C + A 

print "Rl=" & Rl ' resultat non nul 
print "R2=" & R2 ' resultat nul 
End Sub 



v = 7AQ.5 



racine carree de 7 
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Les deux nombres A et B sont voisins mais nettement differents si on tient compte de 
la grande precision du type Double. Cependant, l'execution de la macro donne : 

• Rl = -1,10182045778839 10" 17 

• R2 = 0 

Le pur mathematicien est scandalise : d'abord, il y a une erreur de calcul, et puis 
Basic ne connait meme pas la propriete de commutativite ! En fait, l'erreur decoule 
de la limite de precision pour un Doubl e. 

Ce phenomene se retrouve dans tous les ordinateurs calculant en binaire flottant, et 
s'amplifie avec des calculs en chaine. II n'y a pas de solution simple, des livres et des 
cours traitent des methodes de calcul numerique. 

Les variables monetaires 

Nous avons vu avec les nombres reels que l'implementation est entachee d'une 
imprecision, faible mais inevitable. Les comptables des grandes entreprises, les 
employes de banque ou les fonctionnaires de l'Etat sont amenes a manipuler des 
nombres de tres grande valeur avec plusieurs decimales (en general 2, parfois plus) 
avec une exigence absolue de precision. 

Pour ces usages, Basic fournit le type monetaire appele Currency. Les variables 
monetaires sont implementees sous la forme de nombres entiers de 8 octets, soit 
64 bits. Laffichage d'une variable monetaire considere que les 4 derniers chiffres de 
la representation decimale sont 4 decimales du nombre. Tout se passe comme si une 
valeur de 12345,67 euros etait convertie dans le nombre entier 123456700 pour les 
calculs internes, puis le resultat affiche en positionnant la virgule devant les 
4 derniers chiffres. 

Une variable monetaire admet une precision de 4 decimales sur une gamme de valeurs 
entre -922 337 203 685 477,5808 et + 922 337 203 685 477,5807. Elle s ecrit sans uti- 
liser de symbole monetaire, sans separateur de milliers, et avec un point decimal. 

Dim Budget As Currency 
Budget = 45292790254.35 

Basic initialise les variables Currency a la valeur zero. Reprenons l'exemple des nom- 
bres reels, en employant des variables monetaires : 

rem Code03-03 . odt bibli : Library3 
Option Explicit 



Sub CalculsMonetairesQ 
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Dim A As Currency, B As Currency, C As Currency 
Dim Rl As Currency, R2 As Currency 

A = -1.2345 
B = 1.2346 
C = -0.0001 
Rl = B + A + C 
R2 = B + C + A 

print "Rl=" & Rl ' resultat nul 
print "R2=" & R2 ' resultat nul 
End Sub 

Le resultat affiche sera bien zero pour Rl et pour R2. 

Les operateurs mathematiques pour le type monetaire sont listes au tableau 3-3. 

Les rapports Issue 31001, Issue 54049 et Issue 91121 signalent des anomalies de 
fonctionnement avec les variables de type Currency. Aussi nous deconseillons for- 
mellement l'usage du type Currency tant que ces bogues n'auront pas ete corriges. 

Les variables deci males 

Le type Variant, que nous decrivons plus loin, supporte un sous-type Decimal qui 
n'est pas documente dans OpenOffice. II a ete introduit pour une compatibilite avec 
le type Decimal de VB/VBA, lui aussi sous-type de Variant. On le declare ainsi : 

Dim v As Variant 

v = CDec(0) ' initialiser a zero 

' initialiser a une valeur non supportee par un autre type numerique 
v = CDec("12345. 6789012345678901") 
print v 

La fonction Basic CDec effectue la conversion dans le sous-type Decimal. Elle est 
indispensable pour initialiser une variable dans ce sous-type. Pour l'initialiser a une 
valeur en dehors de la plage admissible pour un type ordinaire, utilisez une chaine de 
caracteres en argument. Les limites du sous-type Decimal sont particulieres : 

• Le nombre maximal de chiffres significatifs est d'environ 28. 

• Pour des valeurs entieres, la limite est 79228162514264337593543950335 en 
positif ou negatif, soit en notation flottante, environ ±7,9E28. 

• La precision decimale maximale est de 28 decimales. 

• La plus petite valeur differente de zero est 0,0000000000000000000000000001 
en positif ou negatif, soit ±lE-28 en notation flottante. 



Le langage OOoBasic 

Deuxieme partie 



Attention 

Un debordement sur une variable de sous-type Decimal ne produit pas d'erreur, le nombre resultant 
sera incoherent. 

Le sous-type Decimal est done preferable au type Currency pour les calculs precis. II 
est aussi utile dans certaines fonctions de l'API qui renvoient ou utilisent des entiers 
a 64 bits (par exemple pour certains types utilises pour les bases de donnees). 

Les operateurs numeriques 

Le tableau 3-3 indique les operateurs disponibles pour chacun des types de donnees 
numeriques. 

Tableau 3-3 Les operateurs numeriques 



Operateur 


Operation 


Byte 

Integer Long 


Single 
Double 


Currency 


Decimal 


+ 


Addition 


Oui 


Oui 


Oui 


Oui 




Soustraction 


Oui 


Oui 


Oui 


Oui 


* 


Multiplication 


Oui 


Oui 


Oui 


Oui 


/ 


Division normale 


Non 


Oui 


Oui 


Oui 


/ 


Division arrondie 


Oui 


Non 


Non 


Non 


\ 


Division entiere 


Oui 


Non 


Non 


Non (Note Q) 


mod 


Reste de la division 
entiere 


Oui 


Non (Notel) 


Non 


Non (Note Q) 


A 


Elevation a la puissance 


Non 


Oui 


Non 


Non (Note Q) 



Notes 

O Les operandes sont convertis automatiquement en Long. 
0 Les operandes sont convertis automatiquement en Double. 



Ordre d evaluation des operateurs numeriques 

Les operateurs numeriques du tableau 3-4 sont presentes par ordre de priorite 
decroissante. Sur chaque ligne, les operateurs ont la meme priorite. Levaluation de 
l'expression s'effectue de gauche a droite quand les operateurs rencontres sont de 
priorite identique. Les parentheses permettent d'imposer un ordre d'evaluation. 
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2 



A 



3 



* / mod 



4 



+ - 



Les booleens 



Les variables booleennes 

Les variables du type Boolean ne possedent que deux valeurs : False (faux) et True 
(vrai). Elles sont tres utiles dans les expressions conditionnelles. 

Elles sont declarees ainsi : 
Dim Out As Boolean 

Basic initialise les variables Bool ean a la valeur Fal se. Ces variables sont stockees en 
interne sous forme de deux octets (16 bits) alors qu'un seul bit suffirait, parce que les 
processeurs courants traitent plus facilement les mots de 16 bits que les elements 
binaires unitaires. Dans Basic, il a ete decide que lors d'une conversion de type : 

• Une valeur numerique nulle est assimilee a Fal se . 

• Toute autre valeur numerique est assimilee a True. 

• Fal se est converti dans la valeur numerique zero. 

• True est converti dans la valeur numerique -1. 

Le code suivant montre diverses manieres d'affecter des valeurs booleennes : 

rem Code03-03 . odt bibli : Library4 Modulel 
Option Explicit 

Sub EvaluationBooleenneO 

Dim Cagnant As Boolean 

Dim Oui As Boolean, Non As Boolean 



' differentes valeurs evaluees a : false 

Cagnant = False 

print "essai IF : ", Gagnant 
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Non = False 
Gagnant = Non 

print "essai 2F : ", Gagnant 
Gagnant = 0 

print "essai 3F : ", Gagnant 

1 differentes valeurs evaluees a : true 
Gagnant = True 

print "essai IV : ", Gagnant 
Oui = True 
Gagnant = Oui 

print "essai 2V : ", Gagnant 
Gagnant = 1 

print "essai 3V : ", Gagnant 
Gagnant = -1 

print "essai 4V : ", Gagnant 
Gagnant = 0.000000000000001 
print "essai 5V : ", Gagnant 
End Sub 



Les operateurs booleens 

Les expressions booleennes utilisent des operateurs particuliers. Dans le tableau 3-5, 
nous emploierons des expressions combinant deux variables ou expressions boo- 
leennes A et B. 

Tableau 3-5 Les operateurs booleens 



not 


not A 


(Operateur NON) 
TruesiAvaut False 
Fal se si A vautTrue 


and 


A and B 


(Operateur ET) 

True si A et B valent True 

Fal se si A vaut Fal se, ou B vaut Fal se, ou les deux valent Fal se 


or 


A or B 


(Operateur OU) 

True si A vaut True ou si B vaut True 
Fal se si A et B valent Fal se 


xor 


A xor B 


(Operateur OU exdusif) 
True si A vaut True et B vaut Fal se 
True si A vaut Fal se et B vaut True 
Fal se si A vaut True et B vaut True 
Fal se si A vaut False et B vaut Fal se 
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Tableau 3-5 Les operateurs booleens (suite) 



eqv 


A eqv B 


(Operateur Equivalence) 
True si A vaut True et B vaut Fal se 
True si A vaut Fal se et B vaut Fal se 
Fal se si A vaut True et B vaut Fal se 
Fal se si A vaut Fal se et B vaut True 


imp 


A imp B 


(Operateur Implication) 

Fal se si A vaut True et B vaut Fal se 

True dans les trois autres cas 



L'expression A eqv B est identique a l'expression not (A xor B). 

L'expression A imp B est identique a l'expression not A or B. L'operateur imp est 
rarement utilise. Le code suivant visualise les differentes combinaisons de 
l'expression : 



rem Code03-03 . odt 
Option Explicit 



bibli : Library4 Module2 



Sub OperateurlmpO 

Dim A As Boolean, B As Boolean 

Dim Resultat As Boolean 



A = False 
B = False 

Resultat = A Imp B 
print A, "Imp", B, 
A = False 
B = True 

Resultat = A Imp B 
print A, "Imp", B, 
A = True 
B = False 

Resultat = A Imp B 



print A, 
A = True 
B = True 
Resultat 
print A, 
End Sub 



'Imp", B, 



= A Imp B 
"Imp", B, 



Resultat 



Resultat 



Resultat 



Resultat 
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Les calculs booleens sur des nombres 



Ces calculs sont utilises rarement, et pour des besoins tres specifiques. Pour com- 
prendre cette section, le lecteur doit etre familier des representations binaires et 
hexadecimales. 

Les operateurs booleens not, and, or et xor peuvent etre appliques sur des variables 
entieres. Dans ce cas, 1' operation est effectuee bit a bit sur la representation binaire 
du contenu des variables entieres, soit sur 16 bits pour des entiers Integer et sur 
32 bits pour des entiers Long. Dans cet exemple, les valeurs indiquees X sont en 
representation hexadecimale : 

rem Code03-03 . odt bibli : Library4 Module3 
Option Explicit 

Sub CalculsBinai res() 
Dim A As Long, B As Long 

A = 513 ' X0201 

B = 776 ' X0308 

print A or B ' affiche : 777 = X0309 

A = 253 ' XOOFD 

B = 42 ' X002A 

print A and B ' affiche : 40 = X0028 

print not A ' affiche : -254 = XFFFFFF02 
End Sub 



Les operateurs de comparaison servent a comparer deux valeurs numeriques (utili- 
sant des entiers ou des reels) ou deux chaines de caracteres. Nous les decrivons ici 
parce que le resultat d'une comparaison est True ou False, c'est-a-dire un resultat 
booleen. La comparaison de chaines de caracteres s'effectue caractere par caractere et 
de gauche a droite, en comparant leurs valeurs Unicode. II en resulte que les majus- 
cules sont distinguees des minuscules, et les caracteres accentues sont differencies. 
Dans le tableau 3-6, nous employons des expressions combinant deux variables ou 
expressions A et B. 



Les operateurs de comparaison 



Tableau 3-6 Les operateurs de comparaison 



Operateur 



Expression 



Resultat 



■ 



A = B 



True si A est strictement egal a B 



<> 



A <> B 



True si A est different de B 



< 



A < B 



True si A est strictement inferieur a B 
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Tableau 3-6 Les operateurs de comparaison (suite) 





<= 


A <= B 


True si A est inferieur ou egal a B 


> 


A > B 


True si A est strictement superieur a B 


>= 


A >= B 


True si A est superieur ou egal a B 



Rappelons que l'egalite entre deux variables ou expressions en nombres reels n'a pas 
de sens a cause des inevitables erreurs de conversion et de calcul. 



Calculs booleens 

Comme les operateurs de comparaison fournissent une valeur booleenne, on peut 
combiner plusieurs de celles-ci avec des operateurs booleens pour obtenir un resultat 
booleen. 

rem Code03-03 . odt bibli : Library4 Module4 
Option Explicit 

Sub Main4() 

Dim x As Long, y As Long 
Dim resultat As Boolean 

x = 347 

resultat = x = 347' style d'ecriture a eviter ! 
print resultat 
y = 6 

resultat = (x = 341) or (y+x-3 >= 350) 
print resultat 
End Sub 

Dans cet exemple, la premiere expression booleenne s'ecrit plus clairement : 
resultat = (x = 347) 

La deuxieme expression de l'exemple combine deux evaluations numeriques avec 
l'operateur booleen or. N'hesitez pas a employer des parentheses pour forcer l'ordre 
d'evaluation d'une expression, et aussi pour rendre l'expression plus lisible. 

Ordre d'evaluation des operateurs booleens et de comparaison 

Les operateurs du tableau 3-7 sont presentes par ordre decroissant de priorite. Sur 
chaque ligne, les operateurs ont la meme priorite. Levaluation de l'expression s'effectue 
de gauche a droite quand les operateurs rencontres sont de priorite identique. 
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Tableau 3-7 Ordre devaluation des operateurs booleens et de comparison 



Priorite Operateurs 


1 (maximale) 


not (operateur unaire) 


2 


<<==<>>=> 


3 


and or xor eqv imp 



Les parentheses permettent d'imposer un ordre devaluation quelconque. N'hesitez 
pas a les employer. 



Les variables de date 

Les variables de type Date servent a memoriser une date et une heure. L'implementa- 
tion du type Date est en fait une variable Doubl e dans laquelle la partie entiere repre- 
sente un nombre de jour, et la partie fractionnaire une heure precise a la seconde, 
exprimee en fraction de jour. Le jour du 30 decembre 1899 a la valeur zero, le lende- 
main a la valeur 1. Basic initialise les variables Date au 30/12/1899 a Oh Omin 0s. 

Le seul moyen d'initialiser une variable Date par programmation est d'utiliser une 
fonction de conversion. II existe une fonction pour obtenir une date, une fonction 
pour obtenir une heure, mais aucune fonction pour initialiser simultanement date et 
heure. Le code ci-dessous montre un exemple simple de variables de type Date. 

rem Code03-03 .odt bibli : Library5 Modulel 
Option Explicit 

Sub LesDatesO 

Dim A As Date, B As Date, C As Date 

A = 15/03/2004 ' ceci ne donne pas ce que vous croyez 
B = DateSerial (2004, 3,15) ' date : 15/03/2004 
C = TimeSerial (9, 57, 35) ' heure : 09h 57mn 35s 
print A, B, C 

A = B + C ' 15/03/2004 a 09h 57mn 35s 
print A 

A = A +320 ' 320 jours plus tard, meme heure 
print A 
I End Sub 

La premiere initialisation de la variable A est acceptee, mais pas comme la date indi- 
quee. En effet, l'expression est evaluee mathematiquement de gauche a droite, et le 
resultat est interprete comme une heure puisqu'il est inferieur a 1. La deuxieme 
affectation de valeur a la variable A permet d'obtenir une date et une heure. La der- 
niere modification de la variable A montre comment on peut changer de jour. 
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La date la plus ancienne qu'on puisse assigner avec DateSerial est l'annee 100, bien 
que cela n'ait pas grand sens puisque le calendrier Gregorien debute en 1582. La date 
la plus futuriste acceptee est le 31/12/9999. Notez que dans les boites de dialogue, le 
controle de champ Date se limite a la periode du l er janvier 1600 au l er janvier 9999. 

Les dates peuvent etre comparees. On peut ajouter ou retrancher un nombre de jours 
ou une valeur d'heure. 

II existe diverses fonctions pour obtenir ou afficher des dates et heures, nous les ver- 
rons au chapitre 5. 



Les objets 

Les variables de type Object sont utilisees pour acceder a des entites qui ne corres- 
pondent a aucun des types connus de Basic. II est impossible d'affecter une valeur de 
type Basic a un objet, car cela declenche une erreur « Utilisation incorrecte d'un 
objet ». Nous utiliserons ce type de variables a partir du chapitre 7, lorsque nous uti- 
liserons l'API OpenOffice.org. En voici un exemple typique : 

Dim monDocument As Object 

monDocument = StarDesktop . 1 oadComponentFromURL( . . . . ) 

A la declaration, la variable Ob j ect ne contient rien. La fonction IsNul 1 renvoie True 
si la variable Object est vide, Fal se si elle contient un objet. 

print IsNull (monDocument) 

II est possible de «vider» une variable Object en lui affectant la pseudo-valeur 
Nothi ng (et non la pseudo-valeur Nul 1 ) : 

monDocument = Nothing 

Ceci est rarement necessaire car Basic libere la memoire des donnees qui ne sont plus 
utilisees, par exemple suite a une nouvelle affectation de valeur ou pour les variables 
locales a la fin d'un sous-programme. 

II existe une forme speciale de declaration d'objet, qui sert a obtenir une variable 
conforme a un « modele ». 

Dim Prop As New com. sun . star . beans . PropertyVal ue 
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Le terme New demande a Basic de creer une nouvelle variable selon le modele qui 
suit. Ce modele est designe par un nom compose, qui doit etre ecrit en respectant les 
majuscules et minuscules. Nous en apprendrons plus sur les noms composes lorsque 
nous aborderons l'API. 



Le type Variant 

Les variables de type Variant sont les plus souples, car elles peuvent contenir des 
donnees des differents types deja vus, y compris un objet. Une telle variable peut 
changer de type au fil des instructions. 

En PRATIQUE Aide en ligne de Basic 

L'aide en ligne traduit Vari ant par « variante » dans le corps du texte. Nous preferons garder le terme 
anglais, avec la majuscule. 

Pourquoi utiliser des Variant ? Si vous concevez une routine dont un argument est 
declare de type Variant, votre routine peut etre appelee avec un argument aussi bien 
de type String que de type Double ou Long, etc. De meme, si vous definissez une 
fonction comme renvoyant un type Variant, tout type de resultat est possible en 
fonction de 1' execution. Enfin, nous le verrons dans d'autres chapitres, le type 
Variant est parfois indispensable avec certaines interfaces de l'API pour lesquelles 
on ne peut connaitre le type de la variable qu'en cours d'execution. 

Basic admet trois formes pour declarer une variable de type Vari ant : 

' on ne declare pas la variable ! ! 
Dim maVariable ' declaration implicite du type 

Dim maVariable As Variant ' declaration explicite du type 

Les deux premieres formes ont deja ete signalees quand nous avons explique les 
declarations de variables. Evitez-les, si vous souhaitez ecrire un code clair. 

A la declaration, la variable Variant ne contient rien. La fonction IsEmpty renvoie 
True si la variable Vari ant est vide, Fal se si elle contient quelque chose. 

print IsEmpty (maVari abl e) 
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II n'existe pas de pseudo-variable pour « vider » une variable Variant. On contourne 
le probleme avec une autre variable non initialisee : 

rem Code03-03 . odt bibli : Library6 Modulel 
Option Explicit 

Sub MainlO 

Dim aa As Variant, vide As Variant 

aa = 3 

print "Valeur de aa : ", aa 
aa = vide 

print "Valeur de aa : " , aa ' ceci n'affiche rien 

if aa = "" then print "Chaine vide" 

if aa <> "" then print "Chaine non vide" 

if aa = 0 then print "Alors aa est nul ?" 

if IsEmpty(aa) then print "aa est vide" 

End Sub 

Lexecution de cet exemple montre plusieurs points remarquables : 

• Le premier pri nt montre bien une valeur numerique. 

• Une fois la valeur Empty affectee a la variable aa, l'instruction pri nt n'affiche plus 
rien, comme pour une chaine vide (c'est-a-dire de longueur nulle). 

• L'instruction suivante n'affiche rien, done aa n'est pas consideree comme une 
chaine vide. 

• L'instruction suivante n'affiche rien non plus, done aa n'est pas non plus une 
chaine non vide ! 

• Le test aa = 0 donne True. Ceci provient d'une conversion implicite de la non- 
valeur du Vari ant en une valeur equivalente pour un nombre entier, qui est zero. 

• Finalement, la fonction IsEmptyO renvoie True, ce qui confirme que aa contient 
la valeur Empty. 

La valeur Null 

Une variable de type Variant peut recevoir une pseudo-valeur : Null. Elle indique 
que la variable ne contient pas de donnee utilisable, ce qui est different d'une variable 
vide. La valeur Null peut etre employee pour renvoyer une donnee signifiant « pas 
d'information » : 



Dim resu As Variant 
' fin d'un traitement 
resu = Null 
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Vous ne pouvez pas utiliser une variable ayant la valeur Null . Les instructions sui- 
vantes provoquent des erreurs : 

Dim aa As Variant, bb As Long 
aa = Null 

bb = aa ' erreur d ' execution car bb n'est pas un Variant 
print aa ' erreur d'execution 

La comparaison d'un Variant a la valeur Null est autorisee. La fonction IsNull 
reconnait l'etat Null du Variant, et la fonction IsEmpty indique que le Variant n'est 
cependant pas vide. 

if aa = Null then print "aa est nul" 

print "Null ?", isNull(aa) ' affiche : True 

print "Empty ?", IsEmpty(aa) ' affiche : False 



Comment connaitre le type d'un Variant ? 

Sachant qu'une variable est de type Variant, comment savoir ce quelle represente a 
un instant d'execution du programme ? Basic fournit a cet effet plusieurs fonctions 
d'interrogation, listees dans le tableau 3-8. Toutes ces fonctions renvoient un resultat 
Boolean : soit True (vrai), soit False (faux). Elles sont aussi utilisables avec tout autre 
type de donnee ou expression. 

Tableau 3-8 Fonctions d'interrogation de type 



IsNull O 


L'argument ne contient pas de donnee utilisable. 


IsEmptyO 


L'argument est vide. 


IsNumeri c() 


L'argument est un nombre entier ou reel ou une chame de caracteres interpretable 
comme un nombre (le separateur decimal est celui de la configuration). 


IsDateO 


L'argument est une date ou une heure. 


IsArrayO 


L'argument est un tableau. 


IsObjectQ 


L'argument est un objet. 



Void un exemple utilisant ces fonctions 



rem Code03-03 . odt bibli : Library6 Module2 
Option Explicit 

Sub Main2() 

Dim aa As Variant, resu As Boolean 



Variables et tableaux de variables 




Chapitre 3 



print "1 Empty ?", IsEmpty (aa) 
print "1 Null ?", IsNull(aa) 
aa = Null 

print "2 Empty ?", IsEmpty (aa) 
print "2 Null ?", IsNull(aa) 
aa = 3.14 

print "3 Empty ?", IsEmpty(aa) 
print "3 Null ?", IsNull(aa) 
print "3 Nombre ?", IsNumeri c(aa) 
print "3 Date ?", IsDate(aa) 
End Sub 



af f i che 
affi che 



True 
Fal se 



affi che 
affi che 



False 
True 



affi che 
affi che 
affi che 
affi che 



Fal se 
Fal se 
True 
False 



Ces fonctions n'ont de sens qu'avec des variables Variant. Demonstration : 

rem Code03-03 . odt bibli : Library6 Module3 
Option Explicit 

Sub Main3() 

Dim aa As Long, resu As Boolean 

print "Empty ?", IsEmpty(aa) ' affi che : False 
print "Null ?", IsNull(aa) ' affi che : False 

print "Nombre ?", IsNumeri c(aa) ' affi che : False 
End Sub 

OpenOffice.org Basic dispose de deux fonctions permettant de connaitre le type 
d'une variable : 

• TypeNameO renvoie une chaine de caracteres precisant le type. 

• VarTypeO renvoie une valeur numerique precisant le type. 
Le code suivant donne quelques exemples. 

rem Code03-03 . odt bibli : Library6 Module4 
Option Explicit 

Sub Main4Q 



Dim aa As Variant, 


bb As Long, cc 


As String 






pn 


nt VarType(aa) , 


TypeName(aa) ' 


affi che : 


0 


empty 


aa 


= 0 










pn 


nt VarType(aa) , 


TypeName(aa) ' 


affi che : 


2 


Integer 


aa 


= 32768 










pn 


nt VarType(aa) , 


TypeName(aa) ' 


affi che : 


5 


Double ! 


aa 


= "12345" 










pn 


nt VarType(aa) , 


TypeName(aa) ' 


affi che : 


8 


String 


aa 


= CDec(O) 










print VarType(aa), 


TypeName(aa) ' 


affi che : 


37 Decimal 
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print VarType(bb) , TypeName(bb) ' affiche : 3 Long 
print VarType(cc), TypeName(cc) ' affiche : 8 String 
End Sub 

Le cas des valeurs entieres montre que le type choisi par une variable Variant n'est 
pas toujours celui qu'on penserait. Nous verrons au chapitre 5 comment imposer cer- 
tains types. Le tableau 3-9 liste les valeurs possibles pour un Variant, certaines sont 
purement internes. 

Tableau 3-9 Valeurs renvoyees par VarType et TypeName 
Type de donnee 



8 


Stri ng 


ChaTne de caracteres 


17 


Byte 


Octet 


2 


Integer 


Entier 


3 


Long 


Entier 


4 


Si ngl e 


Reel 


5 


Double 


Reel 


6 


Currency Monetaire 


37 


Decimal 


Decimal 


11 


Boolean 


Booleen 


7 


Date 


Date 


9 


Object 


Objet 


12 


Variant Variant 


0 


Empty 


Variant vide. 


1 


Null 


Variant : valeur non disponible. 


18 


UShort 


Type interne. 


19 


ULong 


Type interne. 


20 


Long64 


Type interne. 


35 


INT64 


Type interne, utilise par I'API. 


16 


Char 


Type interne, utilise par I'API. 



Les constantes 



Les constantes servent a nommer une valeur fixe, connue a l'ecriture du programme. 



Variables et tableaux de variables 

Chapitre 3 



Une constante s'ecrit avec le mot-cle Const suivi d'une ou de plusieurs definitions 
separees par des virgules. Chaque definition s'ecrit comme si on initialisait une 
variable avec une valeur litterale. La valeur peut etre obtenue par une expression uti- 
lisant des operateurs et des constantes deja definies. 

rem Code03-03 . odt bibli : Library7 Modulel 
Option Explicit 

Sub MainlO 

Dim a As Long, b As Double, p As String 

Const a2 = -314789, poete = "Charles Baudelaire" 

Const e = 2.718281828459045 

Const x = 3*e +1000 +a2 ' constante calculee a parti r de constantes 

a = a2 
b = e 
p = poete 
print p 
print a 
print b 
print x 
End Sub 

Basic affiche un message d'erreur si on essaie de modifier la valeur d'une constante. 
L'usage de constantes rend le code plus robuste que si on ecrivait des valeurs litterales 
au fil des instructions. 

Une constante commune Private, ou Public, ou Global s'ecrit en precedant le mot 
Const d'un de ces termes et en placant la ligne avant les routines. 

Private Const a2 = -314789, poete = "Ronsard" 
Public Const a3 = "Bonjour" 
Global Const a4 = 5.7e6 

Contrairement aux declarations de variables, les constantes Private sont vraiment 
privees. Une constante declaree hors routine seulement avec le mot Const se com- 
porte comme une constante Private. 



Les tableaux 

Jusqu'a maintenant, nous avons etudie des variables simples, qui ont une seule valeur 
a un moment donne. Les variables tableaux (en anglais, array) representent non pas 
une mais plusieurs valeurs simultanees. Elles doivent etre declarees explicitement. 
Les variables tableaux existent dans tous les types de donnees deja rencontres. 



Le langage OOoBasic 

Deuxieme partie 



L'aide F1 de Basic et la documentation Sun traduisent le terme anglais array par le 
mot francais matrice, mais nous preferons et utiliserons le terme tableau. 

Soulignons qu'il nest pas possible de declarer une constante tableau. 



Les tableaux unidimensionnels (vecteurs) 

II s'agit du tableau le plus simple : un ensemble de valeurs accessibles avec un seul 
index. II existe plusieurs manieres de declarer un tableau. Void la plus courante a tra- 
vers un exemple : 

rem Code03-04 . odt bibli : Libraryl Modulel 
Option Explicit 

Sub MainlO 

Dim Temperatures(23) As Double 

Temperatures(O) =4.5 
Temperatures(15) = 13.2 
Temperatures(23) = 6 
End Sub 

L'instruction Dim declare une variable Temperatures qui est destinee a contenir la 
mesure de temperature de la journee, heure par heure. Cette declaration reserve 
24 zones memoire de type Double. On accede a chaque zone avec un index entre 
0 et 23, comme indique dans les lignes suivantes du code. 

Dans cette methode de declaration, le nombre entre parentheses est la valeur la plus 
elevee utilisable de l'index. La valeur la plus basse est zero, ce qui nous donne ici 
24 zones. 

La deuxieme methode nous permet de frxer des valeurs arbitraires aux valeurs 
extremes de l'index. Nous allons supposer que nous memorisons la temperature 
moyenne de chaque mois de l'annee : 

rem Code03-04.odt bibli : Libraryl Module2 
Option Explicit 

Sub Main2() 

Dim Temperatures(l to 12) As Double 

Temperatures(l) = 5 
Temperatures(5) = 13 
Temperatures(8) = 27 
Temperatures(12) = 6 
\ End Sub 
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La declaration de tableau precise les valeurs extremes de l'index. II est possible d'uti- 
liser des valeurs negatives. La valeur apres le to doit etre superieure ou egale a la 
valeur avant le to. 

Dans une declaration Di m , les valeurs d'index peuvent etre des variables. Elles sont 
done determinees seulement a l'execution. 

Dim x As Long, y As Long 

x = -7 

y = x + 40 

Dim v(x to y) As String 



Remarque Taille des tableaux 

Les valeurs extremes de l'index d'un tableau peuvent etre quelconques. Le nombre maximal d'elements 
d'un tableau ne depend que de la memoire disponible. Toutefois, pour des raisons d'implementation, 
chaque element occupe au moins 100 octets en memoire. Ainsi un tableau d'un million d'elements 
Bool ean occupera environ 100 Mo ! 



Les tableaux multidimensionnels 

Supposons que nous ayons besoin de memoriser la temperature de chaque jour de 
l'annee. Nous avons deux solutions : soit utiliser un vecteur avec 366 elements (pour 
tenir compte des annees bissextiles), soit utiliser un tableau a deux dimensions : 

rem Code03-04 . odt bibli : Libraryl Module3 
Option Explicit 

Sub Main3() 

Dim Temperatures(l to 12, 1 to 31) As Double 

Temperatures(l, 1) = 5 ' ler janvier 
Temperatures(5 , 30) = 13 ' 30 mai 
Temperatures (8, 15) = 27 ' 15 aout 
Temperatures(12 , 31) = 6 ' 31 decembre 
End Sub 

Dans la declaration, nous avons indique deux index : le premier pour le numero du 
mois, le deuxieme pour le numero du jour dans le mois. Le contenu de la variable 
Temperatures pourrait etre presente sous la forme d'un tableau de 12 lignes et 
31 colonnes, avec une valeur dans chaque case. Enfin, pas tout a fait... car par 
exemple le 30 fevrier hexiste pas ! Ces cases resteront inutilisees, ce qui n'a aucune 
importance. 
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La premiere forme de declaration peut aussi etre utilisee dans la declaration d'un 
tableau multidimensionnel, pour un ou plusieurs des index. Voici comment memo- 
riser la temperature de chaque heure pour chaque jour de l'annee : 

rem Code03-04 . odt bibli : Libraryl Module4 
Option Explicit 

Sub Main4() 

Dim Temperatures(l to 12, 1 to 31, 23) As Double 

Temperatures(l, 1, 0) = 5 1 ler janvier a OOh 
Temperatures(8, 15, 14) = 27 ' 15 aout a 14h 
End Sub 

On dit que le tableau a trois dimensions. Basic permet un nombre de dimensions 
presque quelconque (dans la mesure des capacites memoire), mais dans la pratique, il 
est rare d'en depasser 4. 

Les tableaux peuvent etre definis en Private, Public, Global comme les variables 
simples. 

Redimensionner un tableau 

II y a des situations ou la taille necessaire pour un tableau varie pendant 1' execution 
du programme. La solution la plus simple est de declarer une taille superieure aux 
besoins prevus et de limiter les valeurs de l'index a la zone utile. Dans la quasi-tota- 
lite des cas, l'occupation memoire reste negligeable par rapport a celle disponible 
pour l'ordinateur. 

Cependant, si vous en avez besoin, Basic permet de redimensionner un tableau en 
cours d'execution du programme, a condition que le tableau soit interne a une rou- 
tine. Pour cela, on utilise l'instruction Redim. 

Cet exemple utilise un vecteur, mais un tableau multidimensionnel aurait convenu. 

rem Code03-04.odt bibli : Library2 Modulel 
Option Explicit 

Sub MainlO 

Dim maTable(3) As Long, Xmax As Long 

maTable(l) = 100 
maTable(3) = 333 

print maTable(l), maTable(2), maTable(3) 
1 quelques instructions plus tard... 
Xmax = 9 
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Redim maTabl e (Xmax) As Long 
maTable(7) = 7777 

print maTable(l), maTable(2), maTable(3), maTable(7) 
End Sub 

Dans ce code, maTabl e est declaree comme vecteur d'index 0 a 3. La premiere ins- 
truction pri nt affiche 100, 0, 333 car l'element d'index 2 a garde sa valeur d'initiali- 
sation. L'instruction Redim transforme maTabl e en vecteur d'index 0 a Xmax, qui 
vaut 9. Attention, Basic refuse de changer le type des elements du vecteur, ou le 
nombre de dimensions du tableau. 

Vous remarquerez que la deuxieme instruction print affiche des zeros pour les 
anciennes valeurs : le redimensionnement a elimine les valeurs qui preexistaient. 
Heureusement, nous pouvons eviter ceci, en utilisant l'option Preserve. 

rem Code03-04 . odt bibli : Library2 Module2 
Option Explicit 

Sub Main2() 

Dim maTabl e(3) As Long, Xmax As Long 

maTabl e(l) = 100 
maTable(3) = 333 

print maTable(l), maTable(2), maTable(3) 
' quelques instructions plus tard... 
Xmax = 9 

Redim Preserve maTabl e (Xmax) As Long 
maTabl e (7) = 7777 

print maTable(l), maTable(2), maTable(3), maTable(7) 
End Sub 

A present, les valeurs preexistantes sont gardees malgre le redimensionnement. Evi- 
demment, il faut pour cela que l'ancien dimensionnement et le nouveau soient com- 
patibles en termes d'index. 



Attention Redimensionnement et vitesse d'execution 

Le redimensionnement d'un tableau represente un certain travail pour Basic, en particulier si on utilise 
Preserve. Comme de nombreux redimensionnements peuvent serieusement ralentir votre pro- 
gramme, il est plus rapide et plus simple de declarer un tableau avec une taille superieure a la tail le 
maximale, et de laisser des elements inutilises. 
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Connaitre les limites d'index 

Dans certaines situations, on se retrouve avec une variable tableau dont on ne connait pas 
la plage des index valides. Basic nous fournit deux fonctions pour nous tirer d'affaire : 

• LBoundO renvoie la valeur minimale de l'index. 

• UBoundO renvoie la valeur maximale de l'index. 

L'exemple suivant est assez artificiel, mais montre comment utiliser ces fonctions. 

rem Code03-04.odt bibli : Library2 Module3 
Option Explicit 

Sub Main3() 

Dim IndexMin As Long, IndexMax As Long 

Dim unVecteur(75 to 139) As Double 

Dim uneTable(5, -3 to 7, 15) As Boolean 

IndexMin = LBound(unVecteurO) 
IndexMax = UBound(unVecteurO) 
print "Vecteur", IndexMin, IndexMax 

IndexMin = LBound(uneTableO) 
IndexMax = UBound(uneTableO) 

print "Table", IndexMin, IndexMax ' premier index 

IndexMin = LBound(uneTable() , 1) 
IndexMax = UBound(uneTable() , 1) 

print "Tab! el", IndexMin, IndexMax ' premier index 

IndexMin = LBound(uneTable() , 2) 
IndexMax = UBound(uneTable() , 2) 

print "Table2", IndexMin, IndexMax ' deuxieme index 

IndexMin = LBound(uneTable() , 3) 
IndexMax = UBound(uneTable() , 3) 

print "Table3", IndexMin, IndexMax ' troisieme index 
End Sub 

Dans I'utilisation de LBoundO et UBoundO, il est necessaire de fournir en argument la 
totalite du tableau. Pour que Basic comprenne notre intention, il est necessaire 
d'ecrire le nom du tableau suivi de deux parentheses sans rien a l'interieur. 

Le deuxieme argument, facultatif, de ces fonctions est le numero de la dimension, ou 
rang de l'index dont on recherche la borne. Pour un vecteur, ce rang est egal a 1. Dans le 
cas d'un tableau multidimensionnel, il vaut entre 1 et n, le nombre de dimensions du 
tableau. Si vous depassez le nombre de dimensions, une erreur sera declenchee. Cela peut 
etre un moyen de connaitre le nombre de dimensions, si vous savez gerer les erreurs. 
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Cette particularity de Basic a ete signalee par Danny Brewer {DannyB) dans le forum de langue anglaise 
OOoForum http://www.oooforum.org/. 



Nous allons essayer d'affecter un tableau a un autre de memes dimensions, en utili- 
sant la syntaxe vue dans la section precedents : 

S4() = S30 

La macro ci-dessous doit etre executee pour afficher les messages. 

rem Code03-04 . odt bibli : Library2 Module4 
Option Explicit 

Sub PointerTableauO 

Dim SI As String, S2(l) As String 

Dim S3(2) As String, S4(2) As String 

S3(0) = "un" 
S3(l) = "deux" 
S3(2) = "trois" 

S4() = S3()' 1 'intention est de copier le tableau S3() 
SI = S3(l) ' copie d'un element de S3() 
' copie d'un element de S3() dans un element de S2() 
S2(l) = S3(l) 

print "Avant", SI, S2(l), S3(l), S4(l) 

S3(l) = "modifie" ' changeons un element de S3() 

print "Apres", SI, S2(l), S3(l), S4(l) 

' conclusion : S3 et S4 pointent sur le meme tableau 

' par contre SI et S2(l) sont bien des copies 

S4(l) = "change"' confirmation en modi fi ant S4 

print "Apres", SI, S2(l), S3(l), S4(l) 

End Sub 

Pour un debutant en programmation, le resultat releve de la magie. Le programmeur 
experimente reconnait un effet de pointeur. Dans l'implementation, la zone memoire 
du tableau se trouve a une certaine adresse, et en realite les variables S3 et S4 ne con- 
tiennent que 1' adresse memoire du tableau : ce sont des pointeurs. 

Lavantage est qu'il n'y a pas de recopie, le pointeur se met simplement jour. Lincon- 
venient est que si nous voulons reellement dupliquer le tableau, nous devrons nous y 
prendre autrement. Notre exemple nous a mis sur la voie : il faut recopier un par un 
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chaque element du tableau. Cette operation est realisee par le code suivant, qui uti- 
lise l'instruction de boucle for que nous verrons au chapitre 4. 

rem Code03-04.odt bibli : Library2 Module5 
Option Explicit 

Sub CopierTableauC) 

Dim S3(2) As String, S4(2) As String 

Dim x As Long 

S3 CO) = "un" 
S3CD = "deux" 
S3C2) = "trois" 

' recopie du tableau element par element 
for x = LBoundCS3C)) to UBoundCS3C)) 

S4Cx) = S3Cx) 
next 

S3 CD = "modi fie" 

print S3C1), S4C1) ' Verification 

End Sub 



Les variables Variant et les tableaux 

Les variables Variant ont des proprietes tout a fait particulieres dans le domaine des 
tableaux. Ces proprietes les rendent indispensables dans certains echanges d'infor- 
mation avec l'API d'OpenOffice.org. 

Les tableaux de Variant 

Un tableau de Vari ant peut etre declare comme le serait un autre tableau : 

Dim TablelC5,3) As Long 
Dim Table2C5,3) As Variant 

Cependant, il existe une grande difference pour le programmeur : la variable Tabl el ne 
peut contenir que des valeurs de type Long, alors que la variable Table2 peut contenir 
simultanement des elements de types differents. Nous pouvons ecrire par exemple : 

Table2C3,l) = -576 
Table2C0,0) = "Mercredi" 
Table2C0,l) = 6.55957 

Comme pour une variable Variant simple, nous pourrions changer le type d'un ele- 
ment au cours du programme. 
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La fonction ArrayO 

Cette fonction est tres pratique pour remplir en une seule instruction une variable 
vecteur avec des valeurs. Si vous etes tres attentif, cette macro devrait vous 
surprendre : 

rem Code03-04 . odt bibli : Library2 Module6 
Option Explicit 

Sub VecteurBizarreO 
Dim unVecteur As Variant 
Dim y As Double 

y = 12345678.9 

unVecteur = array(55555, "Hello", y) 

print unVecteur(O) , unVecteur(l) , unVecteur(2) 

End Sub 

D'une part, nous avons defini unVecteu r comme une variable simple. Et pourtant, nous 
obtenons grace a la fonction ArrayO un vecteur a trois elements ! Dans la declaration, 
nous n'avons pas eu besoin de preciser la taille de l'index. C'est d'un grand interet si vous 
devez recuperer d'une fonction de l'API un tableau dont vous ne savez rien. 

D'autre part, nous avons cree un vecteur contenant un element entier, un element 
chaine de caracteres et un element nombre reel. Ceci est possible car chaque element 
est un Variant. 

Les tableaux de tableaux 

Comme ArrayO accepte des valeurs calculees a l'execution, nous pouvons essayer de 
lui donner en argument un vecteur ! Voila ce que cela donne : 

rem Code03-04 . odt bibli : Library2 Module7 
Option Explicit 

Sub TableauDeTableauxO 

Dim vl As Variant, v2 As Variant, v3 As Variant 
Dim ml As Variant, extrait As Variant 

vl = array(12345, 11) 

v2 = array(43210, 22, 777, 999) 

v3 = array(55555, 3.14, "Hello") 

ml = array (vl,v2,v3) ' construction du tableau 

extrait = ml(l) 

' cette instruction affiche : 3 43210 999 
print UBound(extrait) , extrait(O), extrait(3) 
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extrait = ml(2) 

' cette instruction affiche : 2 55555 Hello 
print UBound(extrait) , extrait(O), extrait(2) 

' *** syntaxe acceptee a parti r de OOo 3.0 *** 
' cette instruction affiche : 43210 2 55555 Hello 
'print ml(l)(0), UBound(ml(2)) , ml(2) (0) , ml(2)(2) 
End Sub 

Nous avons obtenu un etrange tableau compose d'un vecteur a deux elements, d'un 
vecteur a quatre elements et d'un vecteur a trois elements : la variable ml contient un 
tableau de tableaux, ce qui est tres different d'un tableau multidimensionnel. De plus, 
ce tableau est irregulier, car il est constitue d'elements de tailles differentes. L'API 
utilise parfois des tableaux de tableaux. 

II nest pas possible d'obtenir directement un element individuel de la variable ml avec 
une instruction comme ml ( 1 , 1) , car cela declencherait une erreur. En revanche, en uti- 
lisant les proprietes des Variant, on peut recuperer un sous-ensemble, et ainsi de suite 
jusqu'a obtenir un vecteur. Chaque element du vecteur peut alors etre recupere. Dans 
notre codage, nous avons pour cela utilise la variable intermediate extrai t. 

A partir de la version 3.0 d'OpenOffice.org, il est possible d'utiliser une syntaxe spe- 
ciale pour acceder directement a un element de tableau de tableaux : a chaque niveau 
de tableau correspond une indexation entre parentheses (comme dans la derniere ins- 
truction du codage exemple, mise en commentaire pour eviter une erreur de compila- 
tion sur une version ancienne d'OpenOffice.org). Dans un cas general, on peut avoir 
un tableau multidimensionnel de tableaux multidimensionnels. 

Dim a(3,5) As Long, v(6, 4) As Variant 

a(l,4) = 1040 
v(2,3) = a() 

print v(2,3)(l,4) ' affiche 1040 



Structures de donnees complexes 

Cette section s'adresse aux programmeurs experimentes. 

Les collections 

Depuis au moins la version 2.4, le Basic OpenOffice.org est capable de gerer des col- 
lections, a l'image de VBA. Dans une collection, on accede aux donnees par un 
index, ou eventuellement par un nom arbitraire. On peut ajouter, supprimer et lister 
les donnees de la collection. 
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Attention Differentes collections 

Les collections de OOoBasic n'ont rien a voir avec les collections d'objets que nous verrons dans I'API 
OpenOffice.org. Le principe de base est similaire, mais les methodes sont differentes. 
Si votre macro doit fonctionner exclusivement sous MS-Windows, vous pourrez preferer utiliser via COM 
le Scri pti ng .Dictionary, qui offre un mecanisme de collection plus elabore. 



Nous montrerons les differentes possibilites par un exemple qui montre comment 
creer une table de codes postaux qu'on pourra interroger a partir du nom de la com- 
mune. Ici chaque element de la collection est une chaine de caracteres, mais pour 
d'autres utilisations, on pourrait prendre un autre type, par exemple un Variant, ce 
qui ouvre d'autres possibilites. 

rem Code03-05 . odt bibli : Collections Modulel 
Option Explicit 

Sub CodesPostauxO 

Dim codes As New Collection 

codes. Add (" 49000 " , "Angers") ' cle "Angers", valeur 49000, position 1 

codes. Add("33000", "Bordeaux") ' position 2 

codes. Add("09000", "Foix") ' position 3 

codes. Add("11350", "Cucugnan") ' position 4 

print codes("foix") ' code postal de Foix : 09000 

print "Nombre d' elements : " & codes. Count ' 4 elements 

codes .Add("75000" , "Paris", "Foix") 'avant la position de Foix 
print "Valeur de 1' element 4 : " & codes . Item (4) ' Foix 
codes .Add("64200" , "Biarritz", After:= 4) ' apres Foix 
codes. Add("40100", "Dax", Before:= "Biarritz") ' avant Biarritz 
codes . Remove("Bordeaux") 

codes . Remove (3) ' enlever 1 'element 3 : Foix 
codes .Add("Al pha") ' element sans cle 

Dim codePostal As String, n As Long 

For Each codePostal in codes ' explorer la collection 

print codePostal 
Next 

For n = codes. Countto 1 step -1 ' explorer en sens inverse 

codePostal = codes. Item(n) 

print n, codePostal 
Next 
End Sub 
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Une collection est declaree par As New Collection. Initialement, elle est vide. On 
ajoute un element a la collection avec la methode Add, qui prend de 1 a 3 arguments 
(tableau 3-10). Chaque element de la collection se trouve a une position numerotee a 
partir de 1. Si le troisieme argument n'est pas employe, l'element sera ajoute en der- 
niere position. La donnee est quelconque, car le type Vari ant peut accepter tout type 
de donnees, meme un tableau ou un objet. 

Tableau 3-10 Arguments de la methode Add 
Signification 



1 


Variant 


Donnee a memoriser. 


2 


Stri ng 


Optionnel : cle d'acces direct a la donnee. 


3 


Stri ng ou Long 


Optionnel : position d'insertion 
Before : = inserer avant 
After : = inserer apres 

Sans indication, I'insertion s'effectue avant. La position est exprimee 
soit par une cle existante, soit par le numero d'ordre dans la collection. 



La premiere instruction pri nt de notre exemple montre l'interet d'une collection uti- 
lisant des cles : par une pseudo-indexation utilisant la cle (une chaine de caracteres), 
on obtient la valeur de l'element correspondant. La cle est reconnue independam- 
ment de la casse (majuscules/minuscules), mais si elle n'existe pas dans la collection, 
une erreur d'execution sera declenchee. Le nombre d'elements dans la collection est 
obtenu par la methode Count de la collection. 

Les quatre lignes suivantes montrent comment imposer la position d'insertion, avec une 
syntaxe un peu particuliere. Signalons qu'une tentative d'inserer un element avec une cle 
deja utilisee declenche une erreur d'execution. Enfin, il est tout a fait possible d'inserer 
un element sans cle. Dans ce cas le seul moyen de le retrouver est par sa position. 

La methode Remove enleve un element repere soit par sa cle, soit par sa position. 
Pour vider totalement la collection avant de la remplir de nouveau, il suffit de rede- 
clarer la variable : 

Red im codes As New Collection 



La collection peut etre exploree facilement dans le sens des positions croissantes avec 
une boucle For Each, que nous verrons au chapitre 4. II est egalement possible d'uti- 
liser une variable d'index et une boucle For ordinaire, comme nous l'avons fait ici 
pour explorer en sens inverse. Un element de la collection peut etre obtenu soit par 
pseudo-indexation utilisant sa position ou sa cle d'acces, soit par la methode Item 
avec la position ou la cle en argument. 
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Les collections OOoBasic ne comportent actuellement pas de methode pour tester si 
une cle est utilisee. A la place, on peut soit balayer la collection, ce qui peut etre lent 
avec Basic, soit tenter d'acceder a 1' element avec la cle et intercepter l'erreur even- 
tuelle comme indique dans le chapitre 6. 

Les types definis par l'utilisateur 

La plupart des langages de programmation modernes permettent de definir des types 
de donnees adaptes aux problemes a resoudre. OOoBasic offre dans ce domaine les 
types definis par l'utilisateur (en anglais, User Defined Type, UDT). Ce mecanisme 
n'est pas documente, bien qu'existant depuis au moins la version 1.1.4 d'Open- 
Office.org. L'exemple qui suit en montre les possibilites et les limites. II utilise quel- 
ques notions de Basic que nous verrons plus tard. 

rem Code03-05 . odt bibli : TypeUti 1 i sateur Modulel 
Option Explicit 

Type notesCol 1 ege 

Francais As Double 
Maths As Double 
HistGeo As Double 
comportement As String 
End Type 

Type el eve 

nom As String 
prenom As String 
naissance As Date 
poids As Double 
notes As notesCol lege 
End Type 

' utiliser les types declares auparavant 
Sub mani pul erTypeUti 1 i sateur() 

Dim zoe As el eve, n As notesCol 1 ege , p As notesCol lege 
Dim v As Double, clone As Variant 

zoe. nom = "Duschnock" 
zoe. prenom = "Zoe" 
zoe. poids =32.7 

With zoe' With evite de repeter le nom de variable 

.naissance = DateSeri al (1995 , 3 , 27) 

.poids = 34.8 
End With 
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n.Francais = 11.5 
n. Maths = 3 

n.comportement = "Tres dissipee" 
n.HistGeo = 12 

zoe. notes = n ' initialiser tout le sous-type 

p = zoe. notes ' recuperer un sous-type pour le traiter 

p. Maths = p. Maths * 2 ' attention ! on modifie I'original ! 

n.Francais =16 ' ici aussi on modifie zoe . notes . Francai s ! 

clone = zoe 

clone. nom = "Dupont" 1 ici aussi on modifie I'original ! 
v = zoe. notes. Maths ' recuperation d'un sous-element 

MsgBox( "Ne(e) le " & zoe.naissance & chr(13) & _ 

"Maths : " & v & chr(13) & "Francais : " & zoe. notes. Francai s & chr(13) & _ 
"Comportement : " & zoe. notes. comportement, 0, zoe.prenom & " " & zoe. nom) 
End Sub 

Un type defini par l'utilisateur doit etre declare par Type et End Type, et avant toute 
declaration de routine Sub ou Function du module. Un type est constitue d'un ou 
plusieurs elements; chaque element est d'un type Basic (Long, String, Boolean, 
Vari ant, etc.), mais pas un tableau. En revanche un element peut etre d'un autre type 
utilisateur, prealablement declare. Ici, l'element notes est du type notesCollege. 
Bien que la syntaxe d'utilisation soit similaire, un type utilisateur n'est pas une struc- 
ture UNO, et n'est pas utilisable par l'API OpenOffice.org. 

Les variables doivent etre declarees comme etant du type utilisateur ou du type 
Variant, mais pas du type Object. 

Un type defini par l'utilisateur est reconnu seulement dans son module. Pour declarer 
des variables de ce type dans tout autre module Basic, il faut definir dans le module 
initial une fonction destinee a renvoyer une valeur de ce type. En effet, une fonction 
est appelable depuis tout autre module. 

rem Code03-05 . odt bibli : TypeUti 1 i sateur Modulel 

Function CreerEleveO As Variant 
I Dim e As el eve, n As notesCollege 

I e. notes = n ' la sous-structure doit etre declaree expl i ci tement 
CreerEleve = e 
End Function 

rem Code03-05 .odt bibli : TypeUti 1 i sateur Module2 

Sub uti 1 i se rTypeUti 1 i sateu rAi 1 1 eu rs () 
Dim e3 As Variant 
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e3 = creerEleve 

e3.nom = "Ben Sail ah" 
e3.prenom = "Aissa" 
e3. notes. Maths =18.6 

MsgBox("Maths : " & e3 . notes .Maths , 0, e3.prenom & " " & e3.nom) 
End Sub 

Naturellement, il est possible de profiter de cette fonction pour initialiser la nouvelle 
donnee avec certaines valeurs, eventuellement passees en argument. Un type utilisa- 
teur peut contenir un element de son propre type, ce qui nous permet de construire 
des structures chainees. Cependant, il vaut mieux declarer 1' element comme Variant 
pour faciliter le codage Basic. Comme exemple nous prendrons une esquisse de logi- 
ciel de genealogie. Le type Personne permet de remonter au pere et a la mere. La 
fonction qui dam cree et initialise une donnee de type Personne. 

rem Code03-05 . odt bibli : TypeUti 1 i sateur Module3 
Option Explicit 

Type Personne 

Norn As String 

Prenom As String 

Sexe As Boolean 

Naissance As Date 

Deces As Date 

Pere As Variant 

Mere As Variant 
End Type 

' ecrire "" pour une date inconnue (deces) 
' ecrire Null pour un parent inconnu 

Function quidam(Nom As String, Prenom As String, Sexe As Boolean, _ 
Naissance As String, Deces As String, _ 
papa As Variant, maman As Variant) As Variant 

Dim pi As Personne 

pi. Norn = Norn 

pi. Prenom = Prenom 

pi. Naissance = CDate(Nai ssance) 

pi. Deces = CDate(Deces) 

pi. Sexe = Sexe 

pi. Pere = papa 

pi. Mere = maman 

qui dam = pi 

End Function 

Vous trouverez dans le Module4 du meme fichier Code03-05 .odt une mise en ceuvre 
de ces donnees. 
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Variable utilisateur declaree en Global 

Une variable simple de type utilisateur declaree en CI obal est mal memorisee (Issue 52057). Pour con- 
tourner ce bogue, dedarez une variable tableau. 



Diverses fonctionnalites concernant les variables Basic 

Basic possede quelques instructions destinees a simplifier l'ecriture de programmes. 
Nous les signalons afin que vous puissiez les reconnaitre dans vos lectures, mais nous 
deconseillons leur usage. Le gain apparent a l'ecriture sera annule par une perte de 
temps bien plus grande a la mise au point. 



Les caracteres de declaration de type 

Dans une declaration Di m, il est possible de declarer une variable d'un type donne 
sans l'ecrire explicitement. Pour cela, le nom de la variable doit etre termine par un 
caractere special. Ces caracteres sontlistes dans le tableau 3-11. 



Tableau 3-1 1 Liste des caracteres de type 







$ 


Dim unNom$ 


Stri ng 


% 


Dim age% 


Integer 


& 


Dim populations 


Long 


! 


Dim distance! 


Single 


# 


Dim dimension* 


Double 


@ 


Dim budget® 


Currency 


aucun 




Boolean 


aucun 




Date 


aucun 




Object 


aucun 




Variant 



Les caracteres de type pour variables non declarees 

Quand on a la mauvaise habitude de ne pas declarer les variables, il faut un autre moyen 
pour indiquer le type de la variable. Basic utilise dans ce but la premiere lettre du nom de 
la variable. Cette lettre peut etre definie avec une instruction de la forme Defxxx. Par 
exemple, ceci definit les lettres v et z comme lettres designant le type Vari ant : 

DefVar v, z 
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L'instruction Defxxx doit etre ajoutee avant le code du module. Par defaut, aucune 
lettre n'est definie, done toute variable est du type Variant. Malgre cela, certains 
programmeurs ont l'habitude d'utiliser certaines lettres pour indiquer le type de la 
variable. lis mettent cette lettre en minuscule, suivie d'une majuscule pour le 
deuxieme caractere du nom de la variable. 

Le tableau 3-12 liste la lettre usuelle et l'instruction pour chaque type. 

Tableau 3-12 Lettre usuelle et instruction de definition de type 



s 


DefStr 


Stri ng 


i 


Defint 


Integer 


1 


DefLng 


Long 


aucune 


DefSng 


Single 


d 


DefDbL 


Double 


aucune 


DefCur 


Currency 


b 


DefBool 


Boolean 


t 


DefDate 


Date 


0 


DefObj 


Object 


V 


DefVar 


Variant 



Cette maniere de nommer les variables est assez repandue dans les exemples de code 
utilisant les objets de l'API : 

| bSuccess = HasUnoInterfaces(oSimpleFileAccess,IfaceName3$) 

Pour autant, nous insistons sur l'interet de declarer prealablement toute variable que 
vous utilisez, en precisant explicitement le type. Dans ce cas, ce caractere est inutile 
ainsi que celui decrit dans la section precedente. 



DimArrayQ 



Quand on a la mauvaise habitude de ne pas declarer les variables, il faut un autre 
moyen pour definir un tableau. Pour cela, Basic dispose de la fonction DimArray qui 
renvoie un tableau de Vari ant. 

rem Code03-04 . odt bibli : Library2 Module8 



Sub Main8Q 
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unTableau = DimArray(8 , 6 , 11 , 2) 

print UBound(unTableau() , 1), UBound(unTableau() , 2) ,_ 

UBound(unTableau() , 3), UBound(unTableau() , 4) 
End Sub 

Les arguments de Di mA r ray ont la meme signification que pour une declaration de tableau 
avec Di m. On ne peut pas preciser explicitement la borne inferieure de chaque index. 

Option Base 

Si elle est utilisee, l'instruction Option Base doit etre ajoutee avant le code du 
module. Elle sert a definir la limite inferieure par defaut des index de tableau. Vous 
avez le choix entre 0 et 1. 

Option Base 1 

L'instruction ci-dessus definit la limite inferieure a 1, alors que par defaut la limite 
est 0. La valeur par defaut equivaut a ecrire : 

Option Base 0 

II est deconseille de changer la valeur par defaut, car la plupart des programmeurs 
Basic y sont habitues, le gain eventuel en memoire est totalement negligeable et sur- 
tout l'API utilise des index a base zero. 



Conclusion 

OooBasic sait manipuler des entites et des variables de natures differentes. Chacune 
a ses specificites propres : numeriques ou chaines de caracteres, elles ont toutes un 
domaine de definition et d'utilisation identifie. Les variables peuvent etre manipu- 
lees sous forme de tableaux dont nous avons expose les principes et la manipulation. 

Le chapitre suivant nous permettra d'utiliser ces elements a travers des instructions 
conditionnelles et iteratives. 



4 
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Un programme n'est pas un long fleuve tranquille. Les instructions Basic que nous 
allons decrire ici permettent de changer le cours lineaire des instructions executees : 
ce sont les instructions de branchement conditionnel ou inconditionnel, les instruc- 
tions permettant d'effectuer une boucle, et les sous-programmes. 



Instructions conditionnelles 

Ces instructions servent a executer une sequence d'instructions plutot qu'une autre 
suivant la valeur d'une expression conditionnelle. 



If Then Else 

C'est l'instruction conditionnelle la plus courante. Les mots anglais If, Then, Else 
veulent dire respectivement : Si, Alors, Sinon. La signification de cette instruction 
correspond a une phrase equivalente en langage courant. 

If exprl Then 

i nstructi onslv 
Else 

instruct! onslf 
End If 
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Le mot Then doit etre sur la meme ligne que le If (sauf si on utilise le caractere de 
continuation de ligne). Les mots El se et End If doivent etre ecrits sur des lignes dif- 
ferentes, et seuls sur la ligne. On peut ecrire Endlf au lieu de End If. 

Si exprl est vraie, la ou les i nstructionslv sont executees ; si exprl est fausse, la ou 
les instruct! onslf sont executees. Exprl peut etre aussi bien une simple variable 
booleenne, qu'une expression complexe donnant un resultat booleen. 

II doit y avoir au moins une instruction apres le Then. La deuxieme partie Else, 
i nst ructi onslf peut etre omise, mais l'instruction doit toujours se terminer par End If. 

If exprl Then 

i nstructi onslv 
End If 

Lorsqu'une seule instruction suffit dans la partie Then et dans la partie Else, la 
sequence peut s'ecrire sur une seule ligne : 

If exprl Then i nstructionlv Else i nstructi onlf 

Et si la partie El se n'est pas utilisee : 
If exprl Then i nstructi onlv 

Notez l'absence du End If dans ces deux formes simplifiees. 

Une instruction If peut etre imbriquee a l'interieur d'une autre instruction If, dans 
la premiere ou la deuxieme partie. 

If exprl Then 
If expr2 Then 

i nstructions2v 
Else 

i nstructions2f 
Endlf 
Else 

i nstructi onslf 
End If 

Exprl et expr2 sont des expressions booleennes quelconques. Notez que expr2 n'est pas 
evaluee si exprl est fausse. Ceci peut avoir de l'importance dans certaines expressions. 

Limbrication peut se repeter a l'image des poupees russes. En revanche, les 
sequences ne doivent pas se chevaucher, c'est pourquoi il est fortement conseille 
d'ecrire ces instructions avec une indentation (un decalage d'espaces) pour visualiser 
les niveaux d'imbrication. 
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L'imbrication dans la deuxieme partie du If donne : 

If exprl Then 

i nstructi onslv 
Else 

If expr2 Then 

i nstructi ons2v 
Else 

i nstructi ons2f 
End If 
End If 

Ceci etant assez courant, Basic fournit la variante El self (en un seul mot) qui allege 
l'ecriture : 

If exprl Then 

i nstructi onslv 
El self Expr2 Then 

i nstructi ons2v 
Else 

instructions2f 
End If 

Linteret est de pouvoir mettre en cascade des El self pour tester plusieurs cas a la 
suite : 

If exprl Then 

i nstructi onslv 
El self expr2 Then 

i nstructi ons2v 
El self expr3 Then 

instructions3v 
Else 

instructions3f 
End If 

Dans ce dernier exemple : 

• Les i nstructi onslv seront executees si exprl est vraie. 

• Les i nstructions2v seront executees si exprl estfausse et expr2 est vraie. 

• Les i nstructi ons3v seront executees si exprl et expr2 sont fausses et expr3 
vraie. 

• Les i nstructions3f seront executees si exprl, expr2 et expr3 sont simultane- 
ment fausses. 
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Dans les cas ou les conditions consistent a comparer une meme variable avec diverses 
valeurs, l'instruction Select Case, que nous verrons plus loin, est plus appropriee. 

Voici un petit exemple pour illustrer des tests If imbriques. 

rem Code04-01.odt bibli : Conditions Modulel 
Option Explicit 

Sub MainlO 

Dim Homme As Boolean, NombreSpectateurs As Long, Salut As String 

' essayez diverses valeurs 
Homme = False 
NombreSpectateurs = 1 

If NombreSpectateurs > 0 Then 
If Homme Then 

If NombreSpectateurs < 2 Then 

Salut = "Monsieur" 
Else 

Salut = "Messieurs" 
End If 
Else 

If NombreSpectateurs = 1 Then 

Salut = "Madame" 
Else 

Salut = "Mesdames" 
End If 
End If 

print "Bonjour " & Salut 
End If 
End Sub 

Evaluation d'une expression booleenne 

Contrairement a d'autres langages plus sophistiques, OOoBasic evalue la totalite de 
l'expression, de gauche a droite, meme si le resultat devrait etre connu en cours 
d'analyse. 

dim v As Double 

v = 0 

if (v<>0) and ( (5/v) > 10) then 

print "vrai" 
el se 

print "faux" 
end if 
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Malgre les precautions du programmeur, le codage ci-dessus declenche une erreur 
« Division par zero ». En effet, bien que le test v<>0 donne un resultat faux, le reste 
de l'expression est evaluee. 

Dans des cas plus subtils, si la deuxieme partie de l'expression comporte des appels 
de sous-programmes ou methodes de l'API, revaluation involontaire de l'expression 
est susceptible de modifier des etats internes du programme, sans erreur apparente. 
Pour eviter les evaluations non desirees, il faut decomposer l'expression et mettre 
plusieurs if then en cascade. 

Eliminer temporairement une partie de code 

L'EDI ne permet pas de mettre en commentaires d'un seul coup une succession de 
lignes de code. Or ceci s'avere utile pour rechercher un bogue ou pour tester diffe- 
rentes manieres de coder. Une solution astucieuse consiste a encadrer de if ... end 
i f la serie d'instructions a ne pas executer. 

if False then' partie el i mi nee »> 

' ici toute une serie de lignes de codage 

i nstruction 
i nstruction 
i nstruction 

end if «« fin de la partie el i mi nee 



Select Case 

L'instruction Select Case signifie « Selectionner selon le Cas ». Le pseudo-codage 
qui suit liste toutes les variantes possibles : 

Select Case exprO 
Case exprl 

instructionsl 
Case expr2a, expr2b 

i nstructi ons2 
Case expr3a to expr3b 

instructions3 
Case Is OperateurDeComparai son expr4 

instructions4 
' autres instructions Case 
' eventuel 1 ement 
Case Else 

i nstructi onsN 
End Select 
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Les mots-cles doivent se trouver sur des lignes differentes, comme indique ici. II doit 
y avoir au moins un Case expr, alors que la partie Case Else est optionnelle. Les 
termes exprO, exprl, etc. representent des expressions qui fournissent une valeur 
booleenne ou numerique, ou une chaine de caracteres. Chaque Case est suivi par une 
ou plusieurs instructions. 

L'instruction Sel ect Case se deroule ainsi : 

1 La valeur de exprO est comparee a la valeur de exprl. S'il y a egalite, les instruc- 
tions instruct! onsl sont executees, puis 1' execution continue apres le End 
Select. 

2 S'il n'y a pas eu egalite, le Case suivant est teste. La valeur de exprO est comparee 
a la valeur de chacune des expr2 (il peut y en avoir un nombre quelconque). Si 
exprO est egale a une des expr2 alors les instructions instructions2 sont execu- 
tees, puis l'execution continue apres le End Select. 

3 S'il n'y a pas eu egalite, le Case suivant est teste. Si la valeur de exprO est comprise 
entre les valeurs expr3a et expr3b, les instructions instruct! ons3 sont executees, 
puis l'execution continue apres le End Sel ect. 

4 S'il n'y a pas eu egalite, le Case suivant est teste. Le Is (anglais : « Est ») represente 
exprO, qui est comparee a expr4. Si le resultat de la comparaison est vrai, les instruc- 
tions i nstructi ons4 sont executees, puis l'execution continue apres le End Sel ect. 

5 Le processus se poursuit sur les Case suivants tant qu'il n'y a pas d'egalite. 

6 Le Case Else, qui est place en dernier, est declenche en dernier ressort. II n'est 
pas obligatoire. 

Un exemple va montrer les differentes possibilites. Changez les valeurs de x et y pour 
declencher les differentes instructions. 

I rem Code04-01.odt bibli : Conditions Module2 
Option Explicit 

Sub Main2() 

Dim x As Long, y As Long 

y = 10 
x = 1 

Select Case x+7 ' expression donnant une valeur 

Case 3 1 valeur simple 

Print "Case 3" 

Case 7,9 1 liste de valeurs 

Print "Case 7,9" 

Case 8 to 15 1 gamme de valeurs 

Print "Case 8 to 15" 

Case y+12 1 expression donnant une valeur 

Print "Case y+12" 
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Case Is > y+12 ' comparai son d ' expressi ons 

Print "Case Is > y+12" 
Case Else 

Print "autre valeur" 
End Select 
End Sub 

Le Case 7 , 9 se declenche sur l'egalite avec une des valeurs de la liste. 

Le Case 8 To 15 se declenche sur l'ensemble des valeurs de la gamme. Notez que si 
x etait une variable Doubl e, une valeur comme x = 6.35 declencherait le Case. 

Le Case Is est equivalent, localement, a : 
If (x+7) > (y+12) Then Print "Case Is > y+12" 

Bien que le Is puisse etre omis, il est plus clair de le mettre quand on utilise cette 
forme. 

Un autre exemple aurait pu utiliser des expressions chaines de caracteres au lieu 
d'expressions numeriques. 



Ce nom bizarre est probablement l'acronyme de Immediate If. Linstruction Ilf peut 
alleger la programmation par rapport a l'usage d'un If classique. La syntaxe est : 

Resultat = IIf(exprO, exprl, expr2) 

Si exprO est vraie, Resul tat recoit la valeur resultant de exprl. 
Si exprO est fausse, Resul tat recoit la valeur resultant de expr2. 
Linstruction est done equivalente a : 

If exprl Then Resultat = exprl Else Resultat = expr2 

Un exemple simple : 

rem Code04-01 . odt bibli : Conditions Module3 
Option Explicit 

Sub Main3() 

Dim NombreSpectateurs As Long, Salut As String 
NombreSpectateurs = 1 
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Salut = IIf( NombreSpectateurs = 1, "Monsieur", "Messieurs") 
print "Bonjour " & Salut 
End Sub 

Ici les expressions sont tres simples, mais vous pouvez en choisir de bien plus com- 
plexes, comportant meme des Ilf. C'est ce que nous allons faire en reprenant com- 
pletement l'exemple du If Then El se sous une autre forme : 

rem Code04-01.odt bibli : Conditions Module4 
Option Explicit 

I Sub Main4() 

Dim Homme As Boolean, NombreSpectateurs As Long, Salut As String 

1 essayez diverses valeurs 
Homme = False 
NombreSpectateurs = 1 

If NombreSpectateurs > 0 Then 

Salut = IIf( NombreSpectateurs = 1, _ 

Ilf (Homme, "Monsieur", "Madame"), 
IIf(Homme, "Messieurs", "Mesdames") ) 

print "Bonjour " & Salut 

End If 

End Sub 

Pour des raisons de mise en page, la ligne du premier Ilf est repartie sur trois lignes 
avec le caractere de continuation. L'indentation a ete choisie pour mettre en evidence 
les differentes parties de l'instruction qui affecte une valeur a la variable Sal utation. 
Evitez cependant de trop compliquer vos expressions, cela vous epargnera de longues 
recherches d'erreurs. 

Vous pouvez tout a fait utiliser dans un Ilf des expr2 et expr3 donnant des valeurs 
de types differents, si vous y trouvez un usage judicieux. L'exemple suivant est quant 
a lui un peu artificiel. 

rem Code04-01 . odt bibli : Conditions Module5 
Option Explicit 

Sub Main5() 

Dim an As Long, Resu As Variant 
an = 4 ' essayez diverses valeurs 

Resu = IIf((an>=0) and (an<100) , an+2000, "Annee incorrecte") 
print Resu 
End Sub 
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Evaluation des arguments de 1 1 F 

L'instruction II F evalue les deux resultats possibles, quel que soit le resultat de la condition. Ceci est 
intentionnel et conforme au comportement de VBA/VB6. 
Dim v As Double, resultat As Double 

v = 0 

resultat = iif( (v<>0) , 5/v, 1E300) ' erreur : division par zero 
print resultat 

Des comportements anormaux de l'instruction IIF ont ete rapportes (notamment Tissue 63614). Rappe- 
lons qu'elle peut facilement etre remplacee par une sequence i f then el se. 



Choose 

La fonction Choose est une generalisation de la fonction Ilf. Au lieu de se limiter a 
deux alternatives, elle en choisit une parmi plusieurs. La syntaxe de la fonction 
Choose est : 

Resultat = Choose(exprO , exprl, expr2, expr3, expr4(, etc.)) 

Si l'expression exprO vaut 1, Resultat recoit la valeur resultant de exprl ; si exprO 
vaut 2, Resul tat recoit la valeur resultant de expr2, et ainsi de suite. 

Si la valeur de exprO est inferieure a 1 ou superieure au nombre d'expressions qui sui- 
vent, Choose renvoie la valeur Null. Incidemment, ceci vous montre un exemple 
d'utilisation de la pseudo-valeur Nul 1 d'un Vari ant. Toute tentative d'utilisation d'un 
tel resultat entrainera une erreur d'execution. 

Ici encore, les differentes expressions de la liste peuvent etre de differents types. 

Le plus souvent Choose sert a choisir un element dans une liste qui ne sera plus uti- 
lisee ailleurs. Prenons pour exemple un tirage de cartes a jouer : 

rem Code04-01 . odt bibli : Conditions Module6 
Option Explicit 

Sub Main6() 

Dim tirage As Long, carte As String 

'RndO fournit un nombre aleatoire entre 0 et 1 
tirage = Rnd()*12 +1 ' obteni r un entier de 1 a 13 
carte = Choose(ti rage , "As", "Deux", "Trois", "Quatre",_ 
"Cinq", "Six", "Sept", "Hunt", "Neuf", "Dix",_ 
"Valet", "Dame", "Roi") 
print "Tirage :" & tirage, carte 
End Sub 
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Switch 



La fonction Swi tch est encore une autre methode de choix. Elle n'a aucun rapport 
avec la fonction du meme nom du langage C. La syntaxe est de la forme : 

| Resultat = Switch(expbl , exprl, expb2 , expr2, (etc.)) 

Les termes expbl, expb2 designent des expressions a resultat booleen. Les termes 
exprl, expr2 designent des expressions donnant un resultat de type quelconque. 

La fonction Switch utilise des arguments par paires, avec au moins une paire. L'exe- 
cution de la fonction consiste a chercher de gauche a droite la premiere expression 
booleenne qui estvraie (expbl, puis expb2, et ainsi de suite). Dans ce cas, elle renvoie 
la valeur de l'argument suivant. En cas d'echec, la fonction renvoie la valeur Null. 

Lexemple suivant utilise la fonction Switch pour afficher la couleur correspondant a 
la synthese additive des trois couleurs primaires. 



rem Code04-01 . odt 
Option Explicit 



bibli : Conditions Module7 



Sub Main7() 

Dim Rouge As Boolean, Bleu As Boolean, Vert As Boolean 

1 essayez diverses valeurs 
Rouge = true 
Vert = true 
Bleu = true 

print Switch(Rouge and Vert and Bleu, "Blanc", _ 
Rouge and Vert , "Jaune",_ 

Rouge and Bleu, "Magenta", _ 

Rouge , "Rouge", _ 

Vert and Bleu, "Cyan",_ 
Vert , "Vert",_ 

Bleu, "Bleu",_ 
True, "Noir") 

End Sub 



Tout est realise dans l'instruction Print. Le fonctionnement utilise le fait que Switch 
choisit la chaine de caracteres correspondant a la premiere expression booleenne vraie. 
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Structures de boucle 



II est possible d'imbriquer les unes dans les autres les structures de boucles que nous 
allons decrire a present, comme des poupees russes. Cependant, elles ne doivent pas 
se chevaucher (s'entrelacer de maniere decalee). 



Cette boucle permet de repeter un certain nombre de fois les instructions qui sont 
encadrees par For et Next. Syntaxe : 

For index = exprl To expr2 Step expr3 

instructions 
Next 

La variable index est d'un type numerique ; exprl et expr2 sont des expressions 
numeriques qui sont evaluees une seule fois, a l'entree dans la boucle ; expr3 est une 
expression numerique evaluee a chaque tour de la boucle. 

La partie Step et expr3 est optionnelle, elle definit l'increment de la variable index. 
On utilise tres couramment pour expr3 une valeur fixe comme 1 ou -1. Labsence de 
cette partie equivaut a Step 1. 

En pratique, on utilise une boucle For pour incrementer ou decrementer la valeur 
i ndex depuis la valeur exprl jusqu'a la valeur expr2 apres chaque tour de boucle. La 
valeur i ndex est initialisee a exprl. 

Si la valeur expr2 est superieure a la valeur exprl, il s'agit d'une boucle d'incrementa- 
tion. Si expr3 est negatif, la boucle se termine et l'execution reprend apres la ligne Next. 

Si la valeur expr2 est inferieure a la valeur exprl, il s'agit d'une boucle de decrementa- 
tion. Si expr3 est positif, la boucle se termine et l'execution reprend apres la ligne Next. 

Si expr3 a une valeur nulle, la boucle tournera indefiniment ! 

Cet exemple affiche le cube d'une serie de nombres reels : 

rem Code04-01.odt bibli : Boucles Modulel 
Option Explicit 

Sub MainlO 
Dim x As Double 

For x = 37.3 To 63 Step 3.0S8 

print x, x*x*x 
Next 
End Sub 



For Next 
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Remarquez les valeurs successives de x, qui ne sont pas necessairement des entiers. 

On peut repeter dans le Next le nom de la variable de la boucle, ce qui permet une 
verification syntaxique par Basic. II est recommande d'indenter les instructions 
comme dans cet exemple : 

rem Code04-01.odt bibli : Boucles Module2 
Option Explicit 

Sub Main2() 

Dim x As Long, y As Long, z As Long 
Dim maTable(5, 7, 11) As Long 

For x = 0 to 5 
For y = 0 to 7 
For z = 0 to 11 

maTable(x,y,z) = x*10000 + y*100 +z 
Next z 
Next y 
Next x 
End Sub 

L'instruction Exit For permet de sortir prematurement d'une boucle For. L'execu- 
tion reprend apres la ligne Next. 

rem Code04-01.odt bibli : Boucles Module3 
Option Explicit 

Sub Main3() 

Dim uneTable(200) As String 

Dim x As Long, trouve As Boolean 

1 ici uneTable ne contient que des chaines vides 
uneTable(192) = "OpenOffice" ' remplir un element 
trouve = false 
For x = 0 to 200 

If uneTable(x) = "OpenOffice" Then 
trouve = true 
Exit For 
End If 
Next 

If trouve Then print x Else print "Pas trouve" 
End Sub 

Comme l'indique 1' exemple ci-dessus, vous pouvez utiliser la valeur de l'index dans le 
cas d'une sortie par Exit For. En revanche, a la fin normale d'une boucle For, la 
valeur finale de l'index depend de l'implementation. II faut done utiliser un autre 
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moyen pour distinguer la fin normale et la fin prematuree de la boucle. C'est la 
raison de l'indicateur booleen trouve dans notre exemple. 

Dans le cas de boucles For imbriquees, Exi t For termine la boucle la plus interne. 

For Each 

Cette variante de boucle For a ete introduite par la version 2 d'OpenOffice.org. Elle 
est moins generale que son homologue VBA, car elle permet de balayer une variable 
tableau, mais pas une collection de l'API. Avec une boucle For ordinaire, on doit uti- 
liser une variable index et les fonctions LBound et UBound pour connaitre les valeurs 
extremes d'indexation du tableau. La boucle For Each simplifie le codage si on n'a 
pas besoin de l'index. 

Cet exemple utilise une fonction de 1API dont l'utilite importe peu. Elle renvoie un 
tableau de chaines de caracteres que nous allons balayer avec une boucle Fo r a index, 
puis avec une boucle For Each. 

rem Code04-01 . odt bibli : Boucles Module4 
Option Explicit 
Sub Main4() 

Dim t As Variant, v As String, x As Long 

t = ThisComponent.DocumentSubStoragesNames 
print "Boucle For classique" 
For x = LBound(t) to UBound(t) 

v = t(x) 

print v 
Next x 

print "Boucle For Each" 
For Each v in t() 

print v 
Next v 
End Sub 

Nous declarons t comme un simple Vari ant, qui deviendra un tableau de chaines de 
caracteres en recevant le resultat de 1' expression. Nous ne connaitrons la taille du 
tableau qua 1' execution de la macro. Avec une boucle For classique, on obtient les 
limites d'index par LBound et UBound. Ceci nest pas necessaire avec la boucle 
For Each. Les parentheses vides accompagnant la variable t dans l'instruction 
For Each signalent au compilateur que l'ensemble du tableau est utilise. Ce nest pas 
obligatoire, mais facilite la relecture. L'instruction For Each exprime en anglais exac- 
tement ce qui est effectue. Traduction : 



Pour Chaque v Dans t() 
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Do Loop 



La boucle Do Loop execute un nombre de tours non previsibles. Elle s'utilise sous 
plusieurs formes selon l'emplacement de la condition de re-execution : 



' Forme 1 -- 

Do While exprB 
instructions 
Loop 

' Forme 2 -- 

Do Until exprB 
instructions 
Loop 

1 Forme 3 -- 

Do 

i nstructi ons 
Loop While exprB 

' Forme 4 -- 

Do 

i nstructi ons 
Loop Until exprB 



tant que exprB est vraie, f ai re : 
retourner a Do 

jusqu'a ce que exprB soit vraie, f ai re : 
retourner a Do 

f ai re : 

jusqu'a ce que exprB soit vraie 
f ai re : 

retourner a Do jusqu'a ce que exprB soit vraie 



En fait, pour que ces boucles se terminent un jour, il est necessaire que les instruc- 
tions executees modifient des variables utilisees dans la condition. Vous l'oublierez 
regulierement et la boucle tournera indefiniment ! 

L'instruction Exi t Do permet de sortir prematurement d'une boucle Do. Nous pou- 
vons ecrire l'equivalent du deuxieme exemple For ainsi : 

rem Code04-01.odt bibli : Boucles Modules 
Option Explicit 

Sub Main5() 

Dim uneTable(200) As String, x As Long, trouve As Boolean 



' ici uneTable ne contient que des chaines vides 
uneTable(192) = "OpenOffice" ' remplir un element 
x = 0 

Do While x <= 200 

If uneTable (x) = "OpenOffice" Then Exit Do 

x = x+1 
Loop 

If x<=200 Then print x Else print "Pas trouve" 
End Sub 
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Contrairement a la boucle For, le programmeur garde une totale maitrise de sa 
variable de boucle. II existe enfin une derniere forme de boucle Do Loop : 

' Forme 5 

Do ' fan re : 

instructions 
Loop ' retourner a Do 

II s'agit d'une boucle infinie. Dans ce cas, la terminaison de la boucle est decidee 
dans une des instructions encadrees par la boucle, et la sortie est effectuee par un 
Exit Do (ou un Exit Sub, ou un Exit Function comme nous le verrons plus loin). 
Le programmeur choisit en fonction du travail a realiser celle des cinq formes de 
boucle qui donnera le code le plus simple. 

While Wend 

Le terme anglais While signifie « Tant que ». Le terme Wend peut se traduire par 
« Fin du Tant que ». La boucle Whi 1 e repete une serie d'instructions tant qu'une con- 
dition est vraie. La syntaxe est : 

While exprB ' tant que exprB est vraie, f ai re : 

instructions 
Wend ' retourner a While 

Au debut de chaque tour de boucle, l'expression booleenne exprB est evaluee. Si elle 
est vraie, les instructions encadrees par les lignes While et Wend sont executees, puis 
l'execution revient sur la ligne Whi 1 e. Si exprB est evaluee a faux la boucle se termine 
et reprend apres la ligne Wend. C'est exactement le meme principe que la forme 1 de 
la boucle Do Loop, qui est une amelioration du principe de l'ancienne boucle Whi 1 e. 

Lexemple suivant est equivalent au premier exemple de boucle For. 

rem Code04-01.odt bibli : Boucles Module6 
Option Explicit 

Sub Main6() 
Dim x As Double 

x = 37.3 
While x<= 63 

print x, x*x*x 

x = x +3.058 
Wend 
End Sub 
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II n'existe pas d'instruction Exit While pour sortir prematurement d'une boucle 
Whi 1 e. C'est pourquoi la boucle Do Loop est plus pratique. 



Branchements inconditionnels 

Stop, End 

Les deux instructions Stop et End ont la meme utilite : arreter l'execution de la macro 
en cours. Vu l'usage tres courant de End dans d'autres instructions, preferez Stop. 

if x = 0 then 

MsgBox("Valeur interdite !", 16) 

Stop 
end if 
print x 

Normalement, vous ne devriez pas avoir besoin de Stop ou End, l'execution se termine 
quand elle aboutit au End Sub (ou Exit Sub) de la macro principale. Si vous utilisez 
Stop ou End dans un traitement d'anomalie, fermez auparavant vos fichiers ouverts. 

GoTo 

Cette instruction est une des plus anciennes de l'histoire de la programmation. En 
principe, elle ne devrait plus etre utilisee que dans des contextes particuliers, qui sont 
essentiellement lies au traitement d'erreur, que nous verrons au chapitre 6. 

L'instruction GoTo (en francais, Aller a) transfere l'execution du programme a la ligne 
commencant par le nom mis en argument de l'instruction GoTo et immediatement 
suivi par le caractere : . Le point d'arrivee doit se situer a l'interieur de la meme Sub 
ou Function, avant ou apres l'instruction Goto qui la reference. II peut meme per- 
mettre de « sauter » a l'interieur d'une boucle, ce qui evidemment n'est pas du tout 
recommande. 

i nstructi onsl 
GoTo etiquette 
i nstructi ons2 
etiquette: 

instructions3 
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Le nom qui sert d' etiquette suit les memes regies de nommage qu'une variable. Une 
etiquette peut etre referencee par plusieurs GoTo, mais elle n'existe qua un seul endroit. 
II est possible de mettre une instruction a droite de 1'etiquette sur la ligne d'arrivee. 

D'autres langages de programmation disposent d'une instruction Conti nue, qui sert a 
passer a l'iteration suivante dans une boucle. L'instruction GoTo permet de simuler 
cette instruction : 

For x = 1 to 1000 

- instructions - 

- instructions - 

if conditionl then GoTo Conti nuel 

- instructions - 

- instructions - 

if condition2 then GoTo Conti nuel 

- instructions - 

- instructions - 

if condition3 then GoTo Conti nuel 

- instructions - 

- instructions - 
Conti nuel : 

Next x 

Sans l'utilisation du GoTo, il faudrait imbriquer des instructions If ainsi : 

For x = 1 to 1000 

- instructions - 

- instructions - 

if not conditionl then 

- instructions - 

- instructions - 

if not condition2 then 

- instructions - 

- instructions - 

if not condition3 then 

- instructions - 

- instructions - 
end i f 

end if 
end if 
Next x 

Le GoTo est encore parfois utilise par certains programmeurs pour sortir premature- 
ment d'une boucle. Ceci nest pas necessaire avec le Basic d'OpenOffice.org, car il 
dispose pour cela des instructions Exit For et Exit Do que nous avons vues, et des 
Exit Sub et Exit Function que nous verrons plus loin a propos des sous-pro- 
grammes. Ces instructions sont a privilegier, car elles remplissent le meme role sans 
produire une « programmation spaghetti ». 
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Enfin, le GoTo sert en phase de debogage a eliminer temporairement une suite d'ins- 
tructions. Ceci est plus rapide que de mettre en commentaire chaque instruction. 

On Goto 

L'instruction On GoTo permet de poursuivre l'execution a 1' etiquette de meme rang 
que la valeur d'une variable entiere. Exemple : 

rem Code04-01.odt bibli : Branchements Modulel 
Option Explicit 

Sub MainlO 
Dim n As Long 

n = 4 

On n GoTo etiql, etiq2, etiq3, etiq4 

print "Pas de saut" 

GoTo Fini 

etiql: 

print "Nord" 

GoTo Fini 
etiq2 : 

print "Est" 

GoTo Fini 
etiq3 : 

print "Sud" 

GoTo Fini 
etiq4: print "Ouest" 
Fini : 
End Sub 

Si la variable n vaut 4 l'execution se poursuit a eti q4. Si la variable n est inferieure ou 
egale a zero, ou superieure au nombre d'etiquettes en arguments, il n'y a pas de saut 
et l'execution se poursuit a l'instruction suivante. 

L'exemple montre la multiplication inevitable des Goto quand on commence a uti- 
liser ces instructions. Le code devient tres difficile a comprendre, car sa structure 
ecrite ne refiete plus son comportement dynamique. L'instruction On GoTo est a 
bannir, on utilisera a la place la structure Sel ect Case. 



Les sous-programmes 

Un sous-programme consiste a « mettre en boite » tout un codage qui realise un tra- 
vail particulier. On peut alors utiliser un simple nom au lieu d'ecrire une sequence 
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complete d'instructions. On peut meme utiliser un sous-programme ecrit par une 
autre personne, sans se preoccuper de son codage interne : c'est la notion d'abstrac- 
tion, au sens de « faire abstraction des details inutiles ». Ce concept extremement 
puissant permet de construire progressivement des programmes tres sophistiques. 



Le sous-programme le plus courant s'appelle Sub et vous l'avez deja rencontre dans sa 
forme la plus simple. 

Sub monSousProgramme 

' ici toutes les instructions du sous-programme 



Le sous-programme de ce codage a pour nom monSousProgramme. II debute par le 
mot-cle Sub et se termine par les deux mots-cles successifs End Sub. Cet encadre- 
ment doit etre realise comme indique, sur des lignes differentes. 



Attention Nom des sous-programmes 

Le nom d'un sous-programme doit etre unique dans la bibliotheque a laquelle il appartient, car il peut 
etre appele de n'importe quel module. En particulier, il ne faut pas utiliser plusieurs fois un nom comme 
Mai n, meme dans differents modules. 

II est possible de declarer des sous-programmes Pri vate ou Publ i c a I'instar des donnees, mais ceci 
n'est pris en compte qu'en mode de compatibility VBA (voir chapitre 2). 



Appeler un sous-programme 

Un sous-programme est utilise en l'appelant par son nom, sur une ligne. Suivant le 
nombre d'arguments, l'appel se presente differemment. Habituellement, la liste des 
arguments est encadree de parentheses, les arguments etant separes par des virgules. 

monSousProgramme ' aucun argument (lere forme) 

monSousProgrammeO ' aucun argument (2eme forme) 

monSousProgramme(arg) ' un argument (lere forme) 

monSousProgramme arg ' un argument (2eme forme) 

monSousProgramme(argl, arg2 , arg3) ' plusieurs arguments (ici 3) 

monSousProgramme argl arg2 arg3 ' plusieurs arguments (2eme forme) 



Sub 



End Sub 



Basic accepte aussi d'utiliser le mot-cle Cal 1 pour appeler un sous-programme. Pour 
un debutant, ce peut etre un moyen de distinguer l'appel a un sous-programme de 
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l'utilisation d'un mot-cle. Ceci n'est jamais necessaire, meme pour l'appel d'une DLL 
(bibliotheque externe chargee a la demande). 

Call monSousProgramme(arg) 

Un sous-programme peut appeler un autre sous-programme, qui peut lui-meme 
appeler un sous-programme, et ainsi de suite. II est meme possible de concevoir une 
suite d'appels formant une boucle. C'est ce que Ton appelle la recursion. Cette 
methode est tres utile dans certains algorithmes. 

Lordre dans lequel les sous-programmes sont ecrits n'a en general pas d'importance : 
un sous-programme A peut appeler un sous-programme B ecrit avant ou apres lui. 
Dans quelques cas, l'analyseur syntaxique de Basic peut cependant mal interpreter 
vos intentions. Dans nos exemples, nous ecrivons en premier le sous-programme 
principal parce que cela permet de l'executer directement en cliquant sur les icones 
d'execution dans l'EDI. 

Les parametres d'appel de sous-programme 

Pour qu'un sous-programme soit autre chose qu'un simple raccourci, nous avons 
besoin de lui transmettre un ou plusieurs arguments (appeles aussi parametres), dont 
la valeur dependra de nos besoins. 

Les parametres d'un sous-programme sont enumeres dans la ligne Sub, comme dans 
cet exemple : 

Sub monSousProgramme(argl As String, arg2 As Long, arg3 As Long) 

Le nombre de parametres est quelconque. Le nom de chacun est egalement a votre 
choix ; il servira de variable a portee locale dans le corps du sous-programme. Lemploi 
(facultatif) du terme As suivi d'un type est identique a celui deja vu dans l'instruction 
Di m. En effet, nous declarons ici le type de chaque parametre du sous-programme. 

Voici un sous-programme a parametres, base sur 1' exemple utilise plus haut concer- 
nant l'instruction Switch. 

rem Code04-02 . odt bibli : SousProg Modulel 
Option Explicit 

Sub EssaisCouleursO 

Dim maCoul As Boolean 

SyntheseCouleurs(false, true, true) 
maCoul = false 



Alterer le cours du programme 

Chapitre 4 



SyntheseCouleurs(true, true, maCoul) 
End Sub 



Sub SyntheseCouleurs (Rouge As Boolean, Vert As Boolean, Bleu As Boolean) 



print Switch(Rouge and Vert and Bleu 
Rouge and Vert 
Rouge and Bleu 

Rouge 

Vert and Bleu 
Vert 

Bleu 
True 

End Sub 



"Blanc" ,_ 
":aune",_ 
"Magenta",. 
"Rouge", _ 
"Cyan" 
"Vert" ,_ 
"Bleu" ,_ 
"Not r") 



Encore une fois, pour des raisons de mise en page et de lisibilite, nous avons utilise 
des caracteres de continuation pour eviter des lignes trop longues. Le sous-pro- 
gramme SyntheseCouleurs utilise trois parametres, tous de type Boolean, qui sont, 
dans l'ordre, les indicateurs de couleur rouge, verte, bleue. 

Ce sous-programme est appele deux fois dans le corps du sous-programme 
EssaisCouleurs : une premiere fois en donnant directement les valeurs des parame- 
tres, une deuxieme fois en employant une variable. Dans l'appel d'un sous-pro- 
gramme a parametres, l'ordre des arguments doit correspondre a l'ordre dans lequel 
ils sont declares dans l'instruction Sub. 



Parametres optionnels 

Pour simplifier l'usage de certains sous-programmes, il est pratique de rendre option- 
nels un ou plusieurs parametres. Void un petit exemple : 

rem Code04-02 . odt bibli : SousProg Module2 
Option Explicit 

Sub essai sSal utations() 

Sal uer("Bonjour" , 3) ' a une demoiselle 
Sal uer("Bonsoi r" , 1) ' a un monsieur 

Saluer("Bonne soiree") ' a la cantonade, 2e argument absent 
' un appel incorrect, mais accepte par le codage 
Saluer("Salut !", -145) 
End Sub 

Sub Saluer(salut As String, Optional civilite As Long) 
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if IsMissing(ci vi 1 ite) then civilite = 0 
Select Case civilite 
Case 1 

print salut & " monsieur" 
Case 2 

print salut & " madame" 
Case 3 

print salut & " mademoiselle" 
Case Else 

print salut 
End Select 
End Sub 

Le sous-programme Saluer comporte un parametre declare optionnel grace au mot- 
cle Optional. Ce parametre prend normalement une valeur entre 0 et 3. Notez que 
nous avons choisi le dernier parametre. Si nous avions plusieurs parametres option- 
nels, ils devraient etre declares apres tous les parametres obligatoires. En effet, la 
regie d'appel est la suivante : si un parametre est omis, il ne doit plus y avoir d'autre 
parametre utilise a sa droite. 

Comme le parametre ci vi 1 i te peut etre absent, Basic fournit la fonction IsMi ssi ng 
qui renvoie la valeur true en cas d'absence, et false s'il est present. Si le sous-pro- 
gramme comporte plusieurs parametres optionnels, utilisez la fonction IsMi ssi ng sur 
le premier, puis le second, etc., dans l'ordre et de gauche vers la droite. Sans ces pre- 
cautions, vous obtiendrez un resultat aberrant. Si un parametre optionnel est absent, 
il est tout de meme possible de lui affecter une valeur, qui sera utilisee a l'interieur du 
sous-programme. Ceci est impossible avec un parametre de type Object. Employez 
alors soit un type Vari ant, soit une variable locale intermediate. 

Le sous-programme essai sSal utations effectue differents cas d'appels. Le dernier 
appel vous montre que le sous-programme Sal uer est robuste : il fonctionne correc- 
tement et donne un resultat raisonnable parce que nous avons utilise le Case Else 
pour traiter les cas non prevus comme le cas zero. 

Nombre d'arguments transmis au sous-programme 

OOoBasic ne controle pas le nombre d'arguments passes a un sous-programme, 
alors que dans la plupart des autres langages de programmation (Java, Python, 
Pascal...) un nombre incorrect d'arguments est repere a la compilation. Considerons 
un programme principal Test qui appelle un sous-programme True, qui est declare 
avec trois arguments. 

Sub Truc(A,B,C) 

Msgbox "True ! " 
End Sub 
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Sub Test 

Truc() ' aucun argument 

Truc(l,2) ' manque un argument 

Truc(l, 2 , 3 ,4) ' argument excedentai re 
End Sub 

Nous avons place la definition du sous-programme True avant celle du programme 
Test, pour eviter une erreur de syntaxe. En effet, si l'appel de la fonction est place 
avant sa definition, Basic considere que la fonction est alors definie par l'interme- 
diaire du nombre d'arguments passes. Dans notre cas, nous obtenons le message « Le 
symbole True a deja recu une autre definition » car les appels ont indique un passage 
de quatre arguments alors que la declaration Sub n'en contient que trois. 

Dans notre cas, nous definissons au prealable notre sous-programme True, compor- 
tant trois arguments. Executez le sous-programme Test : les trois appels a True sont 
realises sans erreur. 

Vous objecterez que, si True possede trois arguments, ils devraient etre utilises et 
dans ce cas une erreur d'execution apparaitrait. Oui, mais on peut concevoir un sous- 
programme qui n'utilise l'argument C que pour certaines valeurs de A et B. Notez 
que l'usage de la fonction IsMissingO est interdite si l'argument teste n'a pas ete 
declare Optional. 

Ce laxisme sur le nombre d'arguments est utilise dans les exemples de traitement 
d'evenement que nous verrons aux chapitres 11 et 13 : l'objet evenement est toujours 
transmis au sous-programme de traitement, mais celui-ci peut etre declare comme 
n'ayant aucun argument. 

Cette fonctionnalite a done un interet, mais soyez vigilant dans la definition et l'uti- 
lisation de vos sous-programmes Sub et Function. 

Transmission par reference ou par valeur 

Par defaut, les valeurs des parametres employes lors de l'appel d'un sous-programme 
sont transmises par reference. Ceci veut dire que, si vous transmettez une variable, 
celle-ci peut etre modifiee par le sous-programme. Voici un exemple artificiel mais 
demonstratif : 

rem Code04-02 . odt bibli : SousProg Module3 
Option Explicit 

Sub essai sTransmi ssi on () 
Dim pi as Long 
Dim p2 as String 
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pi = 123 
p2 = "Hello" 

print pi, p2 ' afficher les valeurs avant l'appel 
Modifieur(pl, p2) 

print pi, p2 ' afficher les valeurs apres l'appel 
End Sub 



Sub Modifieur( aa As Long, bb As String) 
aa = -4578 
bb = "xxxxx" 
End Sub 

Ce comportement est tout a fait utile dans bien des cas. En revanche, il peut etre la 
cause d'erreurs difficiles a reperer si on a modifie la valeur du parametre par inadver- 
tance. Dans d'autres cas, il est franchement genant. 

Pour eviter de definir dans le sous-programme une variable interne dans le seul but 
de ne pas modifier le parametre transmis, Basic offre 1' option ByVal (abrege anglais 
de By Value, en francais Par Valeur). Modifiez ainsi une des declarations d'arguments 
de la macro Modifieur : 

Sub Modifieur( aa As Long, ByVal bb As String) 

Relancez la macro essai sTransmi ssi on. La variable transmise ne sera plus modifiee. 
Nous avons demande a Basic de passer seulement la valeur du parametre et nous 
pouvons alors utiliser le nom bb comme une variable interne a la macro. 

Les programmeurs puristes utiliseront ByVal chaque fois qu'ils n'ont besoin que 
d'une copie de l'information. Notez cependant que cela induit un (tees leger) ralen- 
tissement du programme. 

Transmettre un tableau dans un parametre 

II est possible de passer un tableau en parametre d'un sous-programme : le nom du 
tableau transmis est alors accompagne de parentheses vides. 

Sub testParamTabl eau () 
Dim tata(5,2) As Double 

tata(l,0) = 123 
tata(2,l) = -5.7 
tata(3,2) = pi 

manipulerTableau(tataO) ' transmettre un tableau 
End Sub 
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Sub manipul erTabl eau( v() As Double ) 
print UBound(v,l) , UBound(v , 2) , v(3,2) 
End Sub 

Le sous-programme manipul erTabl eau declare que son argument d'appel est une 
variable tableau, sans preciser de dimension. Si elles ne sont pas obligatoires, les 
parentheses sont recommandees afin de bien illustrer a la relecture le type de donnees 
que vous aller manipuler. L'instruction print affiche l'index maximal de la premiere 
dimension, l'index maximal de la deuxieme dimension, et un des elements du 
tableau. Dans un codage reel, nous utiliserions les fonctions LBoundO et UBoundO 
pour determiner les dimensions du tableau avant de traiter ses elements. 

Portee des variables d'un sous-programme 

Comme vous avez pu le constater dans quelques exemples, l'instruction Di m est utili- 
sable dans un sous-programme. Elle a pour effet de definir des variables qui ne seront 
reconnues que lorsque Basic execute des instructions de ce sous-programme. En 
dehors de ce sous-programme, ces variables n'existent pas, et par consequent une autre 
partie du programme peut declarer les memes noms de variables pour son propre usage. 

Les noms des arguments du sous-programme sont assimiles a des variables internes, 
avec les memes consequences. Ce comportement, appele localisation des variables, 
est extremement utile dans des programmes assez consequents. En effet, le program- 
meur concevant un sous-programme a ainsi toute liberte de choisir le nom des varia- 
bles internes a ce sous-programme. C'est encore un aspect de la modularite. 

Cet exemple assez extreme demontre l'effet de localisation des variables. II sera 
encore plus instructif avec l'EDI, en affichant en temoin les variables couleur et c et 
en executant la premiere macro avec l'icone Etape par etape de l'EDI. Vous verrez 
ainsi la progression du pointeur d'execution, revolution du contenu des variables, et 
revolution de la pile des appels. 

rem Code04-02 . odt bibli : SousProg Module4 
Option Explicit 

Private couleur As String ' variable connue dans tout le module 

Sub porteeDesVari abl es () 
couleur = "Rouge" 
MsgBox(couleur, 0, "Etape 1") 
SousProglO 

MsgBox(coul eur , 0, "Etape 2") 
SousProg2("Vert") 
MsgBox(couleur, 0, "Etape 3") 
End Sub 
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Sub sousProglO 

Dim couleur As Long ' variable locale masquant la variable Private 
couleur = 12345 
MsgBox(couleur, 0, "Etape 4") 
End Sub 

Sub sousProg2(c As String) 

Dim c As String ' variable locale masquant 1 'argument c 
c = "Marron" 
couleur = c 
End Sub 

Le cas de masquage dans sousProgl peut etre volontaire, si le programmeur n'a pas a 
utiliser la variable Private du meme nom. Le cas de masquage dans sousProg2 est 
une faute de programmation. Dans la realite, elle peut arriver dans des routines utili- 
sant de nombreuses variables, et suite a des changements de codage de la routine. 

Les variables statiques 

Les variables declarees dans un sous-programme sont neuves a chaque nouvelle exe- 
cution du sous-programme. Autrement dit, elles sont initialisees par la declaration 
Di m, comme nous l'avons vu au chapitre 3. 

Lexception a cette regie est la declaration Static. Elle declare une ou plusieurs 
variables, comme Dim. Si vous declarez des variables tableau, les dimensions doivent 
etre fixees a la declaration et ces tableaux ne peuvent etre redimensionnes. Les varia- 
bles declarees Static sont initialisees au premier lancement du sous-programme, 
puis, elles conservent leur valeur d'un lancement a l'autre, jusqu'a la fin de 1' execution 
du programme Basic. 

Le sous-programme principal essai Statique appelle plusieurs fois le sous-pro- 
gramme Tampon qui affiche la valeur de variables Stati c. En executant plusieurs fois 
ce programme, vous verifierez que ces variables sont bien reinitialisees a chaque exe- 
cution Basic. 

rem Code04-02 . odt bibli : Statiques Modulel 
Option Explicit 

Sub essaiStatiqueO 
Do 

voi rTampon 

Loop Until MsgBox("Recommencer ?", 4) = 7 ' sortir si "Non" 
End Sub 

Sub voi rTampon () 

Static Tampon As String, ess(2, 3) As Long 
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' afficher la valeur actuelle du tampon 

MsgBox("Essai " & ess(l, 2) & " Tampon = " & Tampon) 

Tampon = Time ' mettre l'heure courante 

ess(l,2) = ess(l,2) +1 ' compter l'essai 

End Sub 

Fin prematuree d'un sous-programme Sub 

Un sous-programme se termine lorsque le pointeur d'execution rencontre la ligne 
End Sub. Le sous-programme doit parfois se terminer suite a un test conditionnel. 
Pour simplifier et clarifier le codage, Basic offre la possibilite de terminer immediate- 
ment le sous-programme avec l'instruction Exi t Sub, comme dans cet exemple : 

rem Code04-02 . odt bibli : SousProg Module5 
Option Explicit 

Sub DevinetteO 
Dim reponse As String 
Const solution = "27" 
Do 

reponse = InputBox("Devi nez un nombre entre 1 et 99") 
if reponse = solution then 

MsgBox("Bravo, vous avez trouve") 

Exit Sub 
end if 

MsgBox("Rate") 
Loop Until reponse = 0 
End Sub 

Essayez de faire la meme chose sans utiliser Exit Sub, vous verrez que ce n'est pas si 
simple. 

GoSub : le sous-programme interne 

Basic offre une possibilite limitee de declarer des sous-programmes internes a un 
sous-programme. Le sous-programme interne possede un nom, mais ne peut corn- 
porter d'arguments d'appel. II a cependant acces en lecture et ecriture aux variables 
internes du sous-programme principal, ainsi qu'aux parametres de celui-ci. Un sous- 
programme interne est defini ainsi : 

Sub spEnglobant() 

' instructions du sous-programme englobant 
i 

GoSub sousProglnterne' appel 

i 

Exit Sub ' terminer ici 1 'execution principale 
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' definition du sous-programme interne 

sousProglnterne : 

' declarations et instructions 
i 

Return 

End Sub 

Le sous-programme englobant doit se terminer par un Exit Sub derriere lequel on 
place le ou les sous-programmes internes. Ceux-ci sont appeles par l'instruction 
GoSub, qui transfere 1' execution a 1'etiquette indiquee tout en memorisant le point 
actuel d'execution. Le sous-programme interne se termine obligatoirement par une 
instruction Return. 

En employant l'instruction GoSub, vous definissez un veritable sous-programme 
interne a votre routine. On ne peut y rentrer que par 1'etiquette (le nom suivi du 
caractere deux-points), et seulement depuis le sous-programme englobant. Un sous- 
programme interne peut etre utilise plusieurs fois dans votre routine principale, ou 
meme depuis un autre sous-programme interne de la routine principale. Neanmoins, 
ce nest pas le seul interet. 

Les sous-programmes internes peuvent permettre de reduire la complexite d'une 
routine, en donnant un nom clair a une partie de codage qui a une finalite evidente, 
et ceci meme si vous ne l'utilisez qu'une fois. Vous separez ainsi cette partie de 
codage, tout en pouvant utiliser les variables de la routine qui ont deja ete definies. 

Voyez cet exemple de devinette amelioree, qui utilise un seul sous-programme englo- 
bant deux sous-programmes internes. 

rem Code04-02 .odt bibli : PetitJeu Modulel 
Option Explicit 

' utilisation de GoSub pour ameliorer la modularite 
Sub Devinette2 

Dim reponse As Long, nbEssais As Long 
Const solution = 77 

nbEssais = 0 
Do 

GoSub demander valeur 

if reponse = solution then 
GoSub Afficher score 

exit do 
elseif reponse = 0 then 
exit do 
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el se 

print "Perdu, encore un essai ?" 
end "if 
Loop 

print "Jeu termine" 

exit Sub' fin d'execution de Devinette2 



demander val eur : 

dim valTx As String 
do 

valTx = InputBox("Devi nez un nombre entre 1 et 99") 
if valTx = "" then 

reponse = 0 

exit do 
end if 

reponse = CLng(Left(valTx, 3)) 
loop until (reponse>=l) and (reponse<=99) 
if reponse <> 0 then nbEssais = nbEssais +1 
Return' fin de demander_val eur 



Afficher score: 

if nbEssais < 10 then 

print "Vous avez un don de telepathie !" 
elseif nbEssais < 20 then 

print "Pas mal , vous avez trouve en "; nbEssais; " essai s" 
el se 

print nbEssais & _ 

" essais ! La perseverance est toujours recompensee . " 

end if 

Return' fin de Af fi cher_score 

End Sub ' fin du sous-programme Devinette2 

Comparez maintenant la lisibilite avec cette autre version rigoureusement equiva- 
lente, qui n'utilise pas de sous-programme interne. 

rem Code04-02 . odt bibli : Petitleu Module2 
Option Explicit 

' Meme routine principale, mais sans utiliser de GoSub 
Sub Devinette3() 

Dim reponse As Long, nbEssais As Long 
Const solution = 77 
nbEss2ais = 0 
Do 

dim valTx As String 
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do 

valTx = InputBox("Devi nez un nombre entre 1 et 99") 
-if valTx = "" then 

reponse = 0 

exit do 
end i f 

reponse = CLng(Left(valTx, 3)) 
loop until (reponse>=l) and (reponse<=99) 
if reponse <> 0 then nbEssais = nbEssais +1 
if reponse = solution then 
if nbEssais < 10 then 

print "Vous avez un don de telepathie !" 
elseif nbEssais < 20 then 

print "Pas mal , vous avez trouve en "; nbEssais; " essais" 
else 

print nbEssais & 

" essais ! La perseverance est toujours recompenses . " 

end i f 

exit do 
elseif reponse = 0 then 

exit do 
el se 

print "Perdu, encore un essai ?" 
end if 
Loop 

print "leu termine" 

End Sub ' fin du sous-programme Devinette3 

Dans la premiere version, vous saisissez la structure generale du programme dans les 
premieres lignes, qui peuvent s'afficher en totalite a l'ecran. Et chaque sous-pro- 
gramme interne est suffisamment simple pour etre compris rapidement. 

En programmation courante, le GoSub est peu utilise en comparaison des Sub ordi- 
naires, qui permettent des appels avec arguments et une meilleure modularite. 
Cependant CoSub pallie partiellement l'impossibilite actuelle de definir des Sub 
limites a un seul module. 

Function : le sous-programme fonction 

Les fonctions sont des sous-programmes qui renvoient une valeur. Une fonction est 
declaree ainsi : 

Function nomFoncti on (argl As typel, arg2 As type2) As typeN 
1 ici toutes les instructions de la fonction 



End Function 
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Important 

Notez bien le terme anglais Function, avec un u. 



La liste des arguments de la fonction suit les memes regies que pour un sous-pro- 
gramme ordinaire. Le mot-cle As situe apres la liste des arguments precise a 1' appe- 
lant le type de la donnee renvoyee. Le As et le type peuvent etre absents. Dans ce cas, 
la fonction renvoie une donnee de type Variant. 

Toutes les autres fonctionnalites decrites pour les sous-programmes Sub sont dispo- 
nibles avec les sous-programmes Function. Rappelons aussi que l'utilisateur d'une 
fonction peut ignorer le resultat renvoye en utilisant la Function comme une Sub. 

Reprenons le premier exemple de cette section et creons une fonction qui renvoie la 
couleur de synthese sous la forme d'une chaine de caracteres. 

rem Code04-02 . odt bibli : SousProg Module6 
Option Explicit 

Sub essaiCouleurs2() 
Dim couleur As String 

couleur = Synthetiser(true, false, true) 

print "La couleur resultante est : " & couleur 
End Sub 

FunctionSynthetiser(Rouge As Boolean, Vert As Boolean, 
Bleu As Boolean) As String 

Synthetiser = Switch(Rouge and Vert and Bleu, "Blanc", _ 
Rouge and Vert , "Jaune" 

Rouge and Bleu, 



Rouge 



Vert and Bleu 
Vert 

Bleu 
True 



"Magenta" ,_ 
"Rouge" ,_ 
"Cyan" ,_ 
"Vert" ,_ 
"Bleu" ,_ 
"Noi r") 



End Function 



A l'interieur d'une fonction, le nom de celle-ci est utilise comme une pseudo-variable 
a laquelle on affecte une valeur. Ici, la fonction Switch de Basic renvoie une valeur, 
qui est utilisee comme resultat de notre fonction. II est possible d'affecter plusieurs 
fois le resultat de la fonction, au cours de 1' execution de celle-ci. Seule la derniere 
affectation sera renvoyee comme resultat de la fonction. 



Le langage OOoBasic 

Deuxieme partie 



Attention Pseudo-variable « nom de la fonction » 

Cette pseudo-variable « nom de la fonction » doit seulement etre ecrite (en lui affectant une valeur), et 
non lue. Tout autre usage serait confondu avec I'appel de la fonction (qui serait alors un appel recursif). 
Une methode sure consiste a utiliser une variable locale pour calculer le resultat, puis d'affecter ce resul- 
tat a la fonction, de preference a un seul endroit du codage. 



Une erreur courante consiste a terminer une fonction sans lui avoir prealablement 
affecte un resultat, par exemple dans un des cas d'une alternative (if then else ou 
Case). Dans un tel cas, la fonction retourne la valeur par defaut associee a son type de 
resultat (zero pour un type numerique, chaine de caracteres de longueur nulle, ou 
Empty pour un type Vari ant). II est preferable de commencer la fonction en affectant 
des le depart une valeur a son resultat, puis d'affecter une autre valeur selon les condi- 
tions d'execution. 

L'exemple emploie une fonction de Basic. II n'y a pas de difference de principe entre 
une fonction Basic et une fonction que vous realisez vous-meme. 

Fin prematuree d'un sous-programme Function 

Comme pour un sous-programme Sub, il est possible de terminer une fonction avant 
que 1' execution n'arrive a la derniere ligne. On emploie pour cela une instruction 
specifique : 

Exit Function 

N'oubliez pas d'affecter une valeur de retour a votre fonction avant d'executer la ligne 
Exit Function. 

Sous-programmes et bibliotheques 

Nous avons vu au chapitre 2 que les macros sont situees dans des modules, eux-memes 
conserves dans une bibliotheque. Les bibliotheques peuvent vous jouer des tours si 
vous ne prenez pas la precaution de les charger avant d'utiliser une de leurs macros. En 
effet, d'une session a l'autre, ou d'un utilisateur a l'autre, vos macros fonctionneront ou 
non selon que la bibliotheque appelee aura ete chargee ou non par une manipulation, 
parfois involontaire, ou par une autre macro, parfois bien longtemps auparavant. 

Pour appeler une macro situee dans une autre bibliotheque, il faut d'abord s' assurer 
que cette bibliotheque est chargee. Ce chargement peut etre effectue manuellement, 
comme indique au chapitre 2. En revanche, charger une bibliotheque par macro 
necessite des instructions differentes selon la situation. Les instructions permettant 
d'acceder aux bibliotheques font appel a l'API d'OpenOffice.org, dont la syntaxe est 
surprenante pour un debutant. 
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Les conteneurs de bibliotheques Basic 

Une bibliotheque de macros Basic peut etre hebergee dans deux sortes de conteneur : 

• Soit le conteneur appartenant a un document. 

• Soit le conteneur de l'application OpenOffice.org, que nous appellerons soffice. 
Les macros de ce conteneur sont accessibles depuis tout document, ce qui permet 
de constituer des bibliotheques de sous-programmes reutilisables. 

Le conteneur sof f i ce possede deux subdivisions : 

• Mes macros, contenant des bibliotheques creees par I'utilisateur ou par une exten- 
sion installee en mode utilisateur. 

• Macros OpenOffice.org, contenant des bibliotheques mises a disposition par Open- 
Office. org ou creees par une extension installee en mode partage (en anglais 
shared). Ceci est un moyen de rendre disponible des macros communes a tous les 
utilisateurs d'une installation reseau d'OpenOffice.org. Ces macros ne sont pas 
modifiables par I'utilisateur, ce qui est un gage de securite. 

Moyennant eventuellement le chargement de la bibliotheque cible, il est possible 
d'appeler : 

• une macro de sof f i ce a partir d'une macro de sof f i ce ; 

• une macro d'un document a partir d'une macro de ce meme document ; 

• une macro de sof f i ce a partir d'une macro d'un document. 
En revanche, il n'est pas possible d'appeler simplement : 

• une macro d'un document a partir d'une macro de sof f i ce ; 

• une macro d'un document a partir d'une macro d'un autre document. 

Pour ces deux cas, on peut, soit executer une ligne de commande qui lance la macro 
du document, soit charger le document puis utiliser le Dispatcher. Ce dernier cas est 
traite au chapitre 14, section « Utiliser le Dispatcher ». 

Chaque conteneur, soffice ou celui d'un document, comporte une bibliotheque 
Standard qui est systematiquement chargee par OpenOffice. Les autres bibliothe- 
ques doivent etre chargees intentionnellement. 

Si une bibliotheque est protegee par un mot de passe, il reste neanmoins possible, 
sans connaitre le mot de passe, de la charger et d'appeler ensuite les macros de cette 
bibliotheque. Pour autant le contenu de la bibliotheque demeure cache a I'utilisateur, 
et les noms de macros ne sont pas affiches. 
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Charger une bibliotheque Basic du meme conteneur 

II s'agit des cas 1 et 2 cites plus haut. Pour charger la bibliotheque ayant pour nom 
Bi bl i 2, nous devons executer une fois cette instruction : 

BasicLibraries. loadLibrary("Bibli 2") 

Respectez la casse dans l'ecriture du nom de la bibliotheque. Basi cLi bran' es est un 
objet API, dont nous utilisons une methode appelee "loadLi brary (en anglais, 
charger bibliotheque). II n'y a pas d'inconvenient a charger plusieurs fois la meme 
bibliotheque, mais c'est parfaitement inutile. II hexiste pas de moyen de 
« decharger » une bibliotheque, sauf a arreter 1' application OpenOffice.org ou fermer 
le document, si elle se trouve dans un document. 

L'instruction precedents declenchera une erreur s'il n'existe pas de bibliotheque a ce 
nom dans le conteneur. Nous pouvons verifier la presence d'une bibliotheque avec la 
fonction hasByName de l'objet BasicLibraries : 

print BasicLibraries . hasByName ("Tempi ate") 
La fonction renvoie True si la bibliotheque existe, Fal se sinon. 

L'objet BasicLibraries fournit la liste des noms de bibliotheque qu'il connait, sous 
la forme d'un tableau de chaines de caracteres appele ElementNames. Nous allons les 
afficher avec cet exemple, qui donnera des resultats differents selon qu'il est execute 
dans une bibliotheque de sof f i ce ou dans un document. Installez-la dans la biblio- 
theque Standard de Mes macros pour lister toutes les bibliotheques de sof f ice. 

Sub ListerBiblisSofficeO 

Dim lesBiblis As Variant, nomBibli As String 
lesBiblis = BasicLibraries. El ementNames 
for each nomBibli in lesBiblisO 

print nomBibli 
next 
End Sub 

Nous avons ici une application typique de la boucle For Each. 

Charger une bibliotheque Basic d'un autre conteneur 

II s'agit du cas 3 cite plus haut : depuis une macro d'un document, charger une 
bibliotheque de sof f ice. Cette fois-ci nous devons utiliser l'objet Global Scope, qui 
nous expose une propriete BasicLibraries. II suffit de reprendre les instructions 
precedentes en ajoutant Global Scope devant BasicLibraries. 
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Charger la bibliotheque Bi bl i 2 de sof f i ce : 
CI obal Scope. Basi cLi brari es . loadLibrary("Bi bin 2") 

Tester l'existence d'une bibliotheque dans sof f i ce : 
pri nt CI obal Scope . Basi cLi brari es . hasByName("Templ ate") 

Recuperer la liste des noms de bibliotheques de sof f i ce : 
lesBiblis = Gl obal Scope . Basi cLi brari es . El ementNames 

Charger une bibliotheque de soffice au demarrage 

Si vous avez souvent besoin d'une bibliotheque de soffice (ou de plusieurs), il est 
tres simple de la charger au demarrage d'OpenOffice.org avec une petite macro : 

Sub ChargerBiblisO 

BasicLibraries . LoadLibraryC'Tool s") 

End Sub 

Inserez cette macro dans un module de la bibliotheque Standard de Mes macros, qui 
est systematiquement chargee. Declenchez cette macro sur l'evenement Demarrage de 
I'application dans le contexte OpenOffice.org, comme explique au chapitre 1. Un 
precede similaire permettrait de charger une bibliotheque d'un document lors de son 
chargement. 

Appeler une macro d'une autre bibliotheque 

Sans instruction ou manipulation particuliere, une macro est capable d'appeler toute 
autre macro de la meme bibliotheque, ou d'une bibliotheque chargee. Par exemple, 
nous allons charger la bibliotheque Tool s qui se trouve dans sof f i ce, section Macros 
Open-Office.org, et appeler le sous-programme fonction GetProductName situe dans 
le module Mi sc de cette bibliotheque. 

Gl obal Scope . Basi cLi brari es . LoadLi brary ("Tool s") 
print GetProductNameO 

En regie generale, vous obtiendrez ce que vous souhaitez. Mais si, dans votre docu- 
ment, vous avez declare pour vos propres besoins une macro du meme nom, c'est 
cette derniere qui sera appelee. En effet, l'interpreteur Basic recherche le nom 
d'abord dans le meme module que 1' appelant, puis dans la meme bibliotheque, puis 
dans une autre bibliotheque du meme conteneur, puis dans le conteneur soffice. En 
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d'autres termes, il utilise la macro la plus proche de la macro appelante. Pire, si vous 
avez charge plusieurs bibliotheques de sof f i ce, il se peut que plusieurs comportent 
une macro du meme nom. Vous ne pourrez alors pas savoir laquelle sera appelee. Le 
probleme existe dans nos trois cas de configurations appelant/appele. 

La solution consiste a preciser ou trouver la macro appelee en utilisant des 
qualificateurs : nom du module, nom de la bibliotheque, nom du conteneur de 
bibliotheque. Dans notre document exemple nous avons cree une bibliotheque 
Tools, contenant un module Misc, contenant une fonction CetProductname, bref 
tout pour se melanger les pinceaux. Cette macro emploie differents qualificateurs 
devant le nom de la macro appelee. 

rem Code04-02 . odt bibli : SousProg Module7 
Option Explicit 

Sub appelAutreBibli () 

Gl obal Scope . Basi cLi brari es . LoadLi brary ("Tool s") 

print GetProductName() ' a) qualification insuffisante 

print Mi sc .GetProductName() ' b) qualification insuffisante 

print Tools. Misc. GetProductName() ' c) qualification insuffisante 
print Global Scope. Tools. Mi sc. GetProductName() ' d) correct 
print GlobalScope. Tools. GetProductName() ' e) correct 

print GlobalScope. GetProductName() ' f) correct 

End Sub 

Les trois premieres instructions ne trouvent pas la bonne macro, mais elles ont leur 
utilite dans d'autres cas. 

• Linstruction a) correspond au cas habituel : l'interpreteur recherche le nom le 
plus proche. S'il n'y a pas de doublons de nom, cela fonctionne. 

• Linstruction b) permet de resoudre l'ambiguite d'un meme nom employe dans 
deux modules d'une meme bibliotheque. Neanmoins, on voit qu'il est preferable 
d'eviter cette situation. 

• Linstruction c) precise le nom de la bibliotheque, mais une bibliotheque de ce 
nom existe aussi dans notre document. Elle est done choisie en premier alors que 
nous desirions celle de sof f ice. 

• Linstruction d) precise que la bibliotheque se trouve dans sof f i ce, il n'y a plus 
aucune ambiguite. 

• Linstruction e) elimine le nom du module, la qualification reste suffisante dans 
notre cas. 

• Linstruction f) elimine en plus le nom de la bibliotheque. OpenOffice arrive 
encore a retrouver la macro, mais on court un grand risque d'erreur si plusieurs 
bibliotheques sont chargees. 
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Tout ce que nous venons de voir pour l'appel d'une macro est aussi valable pour l'uti- 
lisation d'une variable ou constante Publ i c ou Gl obal d'une autre bibliotheque. 

laBibli .TaVariable = 3 



CONSEIL Renommez ! 

Basic vous propose les noms Libraryl, Library2, etc. pour une nouvelle bibliotheque, et Main 
pour une nouvelle macro. Si vous gardez ces propositions, vous vous retrouverez avec des conflits de 
noms, sans que Basic ne vous previenne. Choisissez done des noms personnalises pour vos macros et 
bibliotheques. 



Conclusion 

Les instructions de branchements conditionnels et iteratifs sont a la base de tout 
algorithme. Elles determinent la logique temporelle du processus. 

Les sous-programmes et fonctions sont indispensables a la structuration de votre pro- 
gramme. Sans eux, point de salut ! lis permettent de « classer » vos developpements 
pour ne pas avoir des centaines de lignes consecutives dont on perd le fil au fur et a 
mesure. Cette structuration permet egalement d'envisager de reutiliser certaines parties 
elementaires de programmes d'une macro a l'autre. Toutefois, vous devez employer cer- 
taines regies pour appeler un sous-programme situe dans une autre bibliotheque. 

Le chapitre suivant nous permettra a present d'approfondir notre connaissance des 
instructions OooBasic de traitement. 
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Les instructions de traitement 



Vous trouverez dans ce chapitre une description de la plupart des instructions Basic que 
nous n'avons pas encore abordees. Lorsque l'aide (F1) est suffisante, nous nous conten- 
terons de signaler l'instruction, et il suffira de vous y reporter. Dans d'autres cas, nous la 
corrigerons ou nous developperons des aspects non decrits ou mal expliques. 

Dans la section consacree aux fonctions de conversion, nous vous expliquerons en quoi 
les conversions automatiques de Basic sont souvent utiles et parfois dangereuses. 

A partir de ce chapitre, lorsque nous utiliserons 1' expression « 1' argument est du type 
xxx », cela signifiera que Basic accepte comme argument une variable de ce type, ou 
une valeur ecrite directement, ou toute expression dont revaluation donne une valeur 
de ce type. De plus, Basic effectue automatiquement des conversions de type lorsque 
c'est necessaire pour revaluation. 

Vous decouvrirez que Basic offre de nombreuses fonctions. Si vous ne trouvez pas ce 
que vous cherchez, peut-etre pourrez-vous la realiser en quelques lignes de codage. Si 
vous avez besoin d'une des fonctions de Calc, le chapitre 9 vous apprendra a la 
mettre en oeuvre dans un programme Basic. 
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Les chaines de caracteres 

Longueur d'une chaine 

La fonction Len sert a determiner la longueur d'une chaine, en nombre de caracteres. 
La valeur renvoyee est de type Long. Tester si une chaine est nulle peut se faire de 
deux manieres : 

"if chaine = "" then 1 premiere methode 

"if Len(chaine) = 0 then ' deuxieme methode 

Comparer deux chames de caracteres 

La fonction StrComp compare les chaines de caracteres Textl et Text2. Elle renvoie 
-1 ou 1 selon que Textl est alphabetiquement classe avant Text2 ou apres ; elle ren- 
voie zero en cas d'identite. 



Complement sur la syntaxe 

Pour trouver la syntaxe de StrComp, appuyez sur la touche F1 depuis I'EDI puis, dans I'onglet Index, 
tapez le nom recherche. 

A noter : 

• Lorsque le parametre Compare est omis, ceci est equivalent a mettre la valeur 1, 
done une comparaison tenant compte de la casse. 

• D'une maniere generate, chaque caractere est « pese » selon sa valeur donnee par 
la fonction ASC, la comparaison s'effectuant caractere par caractere, de gauche a 
droite. 

• Un caractere chiffre est classe avant tout caractere alphabetique. 

• Un caractere majuscule non accentue est classe avant tout caractere minuscule et 
tout caractere accentue. 

• N'importe quel caractere est « plus lourd » que 1' absence de caractere : « soleil » 
est classe avant « soleil » (comportant un espace final). 

Comparaison a un modele generique 

Loperateur Like, non documente, permet une comparaison entre une chaine de 
caracteres et son modele. Le resultat de la comparaison est une valeur booleenne, 
True ou False. Loperateur Like de OOoBasic ne tient jamais compte d'une diffe- 
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rence de casse (majuscules ou minuscules) ; un caractere accentue est toujours diffe- 
rent du meme caractere sans accent ; un digramme (par exemple la lettre a) ne peut 
pas etre assimile a deux lettres (ae). 

Le modele est une chaine de caracteres pouvant comporter des caracteres 
generiques : 

• Un caractere * represente un nombre quelconque de caracteres (y compris aucun). 

• Un caractere ? represente un caractere quelconque. 

• Un caractere # represente un chiffre. 

• Une sequence, par exemple [AZ9H], represente un caractere dont la valeur doit 
correspondre a un de ceux listes entre les crochets. 

• Une sequence comme [D-X] represente un caractere dont la valeur doit etre dans 
la serie de caracteres representee par les deux caracteres entourant le tiret ; dans 
cet exemple, un caractere compris entre D et X (E, F, C...). 

• Une sequence debutant par un caractere !, comme [!0-9], represente un carac- 
tere qui ne doit prendre aucune des valeurs cities. 

Qyelques exemples : 

rem Code05-01 . odt bibli : Standard Modules 
Option Explicit 

Sub comparerAuModel e 

Dim s As String, modele As String 

modele = "??#_*" 
s = "123_" 

print "Resultat 1 : " & (s Like modele) ' donne : True 
s = "Aa8_tatata" 

print "Resultat 2 : " & (s Like modele) ' donne : True 
s = "F3_sss" ' il manque un caractere avant le "souligne" 
print "Resultat 3 : " & (s Like modele) ' donne : False 

modele = "x[B-F]*machin" 

s = "XE233Machin" 

print "Resultat 4 : " & (s Like modele) ' donne : True 
s = "XG233Machi n" ' deuxieme caractere inacceptable 
print "Resultat 5 : " & (s Like modele) ' donne : False 
s = "xfa5dty+:?/Machin" 

print "Resultat 6 : " & (s Like modele) ' donne : True 
s = "xfa5dty+:?/Machine" ' le e final est inacceptable 
print "Resultat 7 : " & (s Like modele) ' donne : False 

modele = "[A-Z] [hxl-5]*" 

s = "b52" 

print "Resultat 8 : " & (s Like modele) ' donne : True 
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S = "AH" 

print "Resultat 9 : " & (s Like model e) ' donne : True 
s = "c3" 

print "Resultat 10 : " & (s Like model e) 1 donne : True 
s = "c6" ' chiffre hors de la plage acceptable 
print "Resultat 11 : " & (s Like model e) 1 donne : False 

model e = " [ ! i 1 ol] [ ! 0-9] " 
s = "Bh" 

print "Resultat 12 : " & (s Like model e) ' donne 
s = "B7" 

print "Resultat 13 : " & (s Like model e) ' donne 
s = "IZ" 

print "Resultat 14 : " & (s Like model e) ' donne 
End Sub 

Rechercher une chaine dans une autre chaine 

La fonction InStr recherche, a partir de la position Start, la premiere apparition de 
la chaine Text2 dans la chaine Textl et renvoie la position du premier caractere con- 
cordant. La position trouvee, de type Long, est comptee a partir de 1. Si Text2 ne se 
trouve pas dans Textl la fonction renvoie zero. 



Complement sur la syntaxe 

Pour trouver la syntaxe de InStr, appuyez sur la touche F1 depuis I'EDI puis, dans I'onglet Index, tapez 
le nom recherche. 



A noter : 

• Le parametre Start doit prendre la valeur 1 pour une recherche a partir du debut 
de la chaine Textl. II est plus clair de ne pas omettre ce parametre. 

• Lorsque le parametre Compare est omis, ceci equivaut a mettre la valeur 1, done 
une comparaison sans tenir compte de la casse. II est plus clair de ne pas omettre ce 
parametre. 

Quelques exemples : 



Dim 


a As String, 


b As Long 








a = 


"Bonjour" 










b = 


InStr(3, a, 


"o", 0) ' 


b 


recoit 


5 


b = 


InStr(l, a, 


"o", 0) ' 


b 


recoit 


2 


b = 


InStr(l, a, 


"JO", 0) ' 


b 


recoit 


0 


b = 


InStr(l, a, 


"JO", 1) ' 


b 


recoi t 


4 



i rue 
False 
Fal se 
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Le couteau a decouper : Mid 

La fonction Mi d renvoie une chaine de caracteres qui est un troncon de la chaine ini- 
tiale. La fonction Mi d possede 2 ou 3 parametres. 

Dim a As String 

a = Mid("Bonjour" , 4) ' a recoit "jour" 
a = MidC'Bonjour", 5,2) ' a recoit "ou" 

L 'instruction Mi d remplace un troncon d'une chaine de caracteres par une autre chaine 
de caracteres de longueur au plus egale a celle du troncon. Linstruction Mi d possede 
toujours 4 parametres. 

a = "Bonjour" 

Mid(a, 4, 3, "soiXXX") ' a devient "Bonsoir" 
a = "Bonjour" 

Mid(a, 1, 4, "J") ' a devient "Jour" 



Complement sur la syntaxe 

Pour trouver la syntaxe de Mi d, appuyez sur la touche F1 depuis I'EDI puis, dans I'onglet Index, tapez le 
nom recherche. 

A noter : 

• Les parametres Start et Length sont du type Long et non Integer. La position 
d'un caractere est comptee a partir de 1. 

• Si la chaine de remplacement est plus longue que le troncon, la partie gauche de 
la chaine est utilisee. 

• Si la chaine de remplacement est plus courte que le troncon, le troncon complet 
est remplace par la chaine. 

• Si la chaine de remplacement est de longueur nulle, le troncon est supprime de la 
chaine initiale. 



Supprimer des caracteres a gauche et a droite 

Les fonctions LTrim, RTrim et Trim servent a debarrasser une chaine de caracteres 
d'espaces inutiles places respectivement en debut, en fin et aux deux bouts de la 
chaine. Ces fonctions renvoient la chaine de caracteres resultante. 

Les fonctions Left et Right servent a recuperer la partie gauche, respectivement 
droite, de la chaine donnee en argument. Si n est superieur a la longueur de la chaine, 
la totalite de celle-ci est renvoyee. 
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Decouper et recoller une chaine 

La fonction Spl i t decoupe une chaine de caracteres en suivant un caractere de deli- 
mitation de segments. Elle renvoie un tableau de chaines de caracteres. 

La fonction Join aboute les elements d'un tableau de chaines de caracteres en insu- 
rant eventuellement un separateur entre chaque troncon. 

Lexemple de l'aide en ligne etant trop complexe, nous en donnerons un autre. Ce 
dernier decoupe la chaine Cible a chaque caractere point- virgule, et renvoie cinq 
segments. Une boucle For affiche chaque segment. Puis le tableau obtenu est recolle 
avec un separateur barre de fraction. Notez bien la maniere de declarer le tableau et 
de le transmettre a la fonction Don n. 

rem Code05-01.odt bibli : Standard Modulel 
Option Explicit 

Sub demoSplitO 

Dim Cible As String, resu() As String, x As Long 

Cible = "alpha;beta;gamma;delta;epsilon;phi" 

resu = Split(Cible, 5) ' decoupe en 5 segments max 

for x = LBound(resu) to UBound(resu) 

print x, resu(x) ' dernier segment : epsilon;phi 
next 

Cible = Join(resu(), "/") 

print Cible ' resultat : alpha/beta/gamma/delta/epsilon;phi 
,i End Sub 



Remplacer partout dans une chaine de caracteres 

II existe une fonction Replace non documentee, qui ne fonctionne pas (Issue 94895). 
Mais la combinaison des fonctions Split et Join permet de remplacer toute occur- 
rence d'une sous-chaine dans une chaine, de maniere tres elegante et rapide. Par 
exemple, ceci remplace les lettres « e » par des « e ». 

Dim a As String 

a = "L'eleve a eternue" 

a = Join (Split (a, "e") , "e") 

Creer une chaine de caracteres 

La fonction String cree une chaine constitute de la repetition du meme caractere. 
La fonction Space est une specialisation de String dans laquelle le caractere repete 
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est un espace. Ces deux fonctions sont surtout utiles pour definir des chaines tres 
longues, jusqu'a 65 535 caracteres. Notez que le parametre n des fonctions Stri ng et 
Space est de type Long, et non Integer. 

Aligner a gauche ou a droite 

Les instructions LSet et RSet servent a aligner un texte dans une « zone blanche ». 
Elles ne suivent pas la syntaxe habituelle, mais celle-ci : 

RSet vl = v2 

Dans cette expression, vl est une variable de type String, v2 est une variable ou 
expression du type String. Seule la longueur de vl est importante, pas son contenu, 
qui sera perdu. La variable vl recoit la chaine v2 cadree a droite dans cette longueur, 
et completee a gauche par des espaces. Linstruction Lset, elle, cadre v2 a gauche et 
complete a droite par des espaces. 



Les fonctions numeriques 

Signe et valeur absolue 

La fonction Sgn renvoie un nombre entier permettant de determiner si le nombre en 
argument est negatif, positif, ou nul. Largument peut etre de type entier ou reel. 

La fonction Abs renvoie un nombre Double qui est la valeur absolue du nombre 
donne en argument. Largument peut etre un nombre entier ou un nombre reel. 

Fonctions trigonometriques 

Les fonctions Si n, Cos et Tan renvoient respectivement la valeur du sinus, du cosinus 
et de la tangente d'un angle exprime en radians. La valeur absolue de Tangle doit etre 
inferieure a 2 71, sinon le resultat sera incorrect. La fonction Atn renvoie l'arc-tan- 
gente de l'argument. 

Signalons que Basic connait la constante Pi, avec la precision necessaire pour les 
types reels. 



Autres fonctions mathematiques 

La fonction Log renvoie le logarithme neperien de l'argument. 
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La fonction Exp renvoie l'exponentielle (au sens mathematique) de l'argument. 
La fonction Sq r renvoie la racine carree de l'argument. 

Nombre aleatoire 

A chaque appel, la fonction Rnd renvoie un nombre pseudo-aleatoire (c'est-a-dire 
genere mathematiquement pour assurer une distribution des valeurs tees proche du 
hasard) de type Doubl e, dont la valeur est comprise entre zero et un. Une simple mul- 
tiplication permet ensuite d'ajuster la gamme des valeurs possibles. 

Linstruction Randomize initialise le generateur pseudo-aleatoire. En donnant un 
nombre en argument de Randomi ze, le generateur de Rnd produira toujours la meme 
serie de valeurs pseudo-aleatoires, ce qui peut faciliter la mise au point du programme. 



Les fonctions de date et heure 

La fonction Now renvoie la date-heure actuelle sous la forme d'une donnee de type Date. 

La fonction Time renvoie l'heure actuelle sous la forme d'une donnee de type Date 
dont seule la partie heure est significative. L'heure est precise a la seconde. 

La fonction Date renvoie la date actuelle sous la forme d'une donnee de type Date 
dont l'heure est nulle. 

La fonction Timer renvoie le nombre de secondes ecoulees depuis minuit. Le resultat 
de la fonction ne peut pas etre utilise directement, on doit l'affecter d'abord a une 
variable de type Long. 

Linstruction Wait effectue une temporisation, sans pour autant bloquer le systeme 
d'exploitation. Attention aux reactions de l'utilisateur pendant cette duree ! L'argument de 
Wai t est le nombre de millisecondes d'attente. La precision de la temporisation depend du 
systeme d'exploitation, elle est de 16 millisecondes sur un compatible IBM-PC. 

La fonction GetSystemTicks renvoie un entier Long qui est la valeur actuelle d'un 
compteur incremente par le systeme d'exploitation. La signification de ce compteur 
depend de celui-ci. Sur un ordinateur compatible IBM-PC, la valeur est un nombre 
de millisecondes avec un pas d'environ 16 millisecondes, ce qui est suffisant pour 
mesurer des delais courts. 

Dim t As Long 

t = GetSystemTicks 

wait 1000 ' simulation d'un processus a mesurer 
t = GetSystemTicks -t 
MsgBox("Nombre de Ticks : " & t) 
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A RETENIR Penser a I'utilisateur 

L'utilisateur s'inquiete rapidement si son programme semble se figer (1 5 secondes sont pour lui une eter- 
nite). II est alors tente de taper au clavier ou de cliquer avec la souris « pour debloquer I'application ». Le 
resultat peut etre catastrophique si votre programme effectuait un traitement un peu long. Vous trouve- 
rez au chapitre 14 quelques methodes pour eviter ce probleme. 



Fonctions de modification de date-heure 

Le detail de ces fonctions est precise dans l'aide F1 de Basic, cherchez le nom de la 
fonction dans l'index. Elles prennent toutes en argument une valeur du type Date. 

DateDiff 

La fonction DateDi f f renvoie la difference entre deux dates, en nombre de jours, ou 
mois, ou annees, etc. 

Dim dl As Date, d2 As Date 
dl = "15/04/2006" 
d2 = "14/7/1998" 

MsgBox("Ecart en jours : " & DateDi ff("d" , d2 , dl)) 
MsgBox("Ecart en mois : " & DateDi ff("m" , d2 , dl)) 
MsgBoxC'Ecart en semaines : " & DateDiff ("w" , d2 , dl, 2, 1)) 

DateAdd 

La fonction DateAdd renvoie une date decalee de la premiere d'un certain nombre de 
jours, ou mois, ou annees, etc. 

Dim dl As Date 
dl = "27/04/2006" 

MsgBox("Tri mestre dans l'annee : " & DatePart("q" , dl)) 

MsgBox("Jour dans l'annee : " & DatePart("y" , dl)) 

MsgBox("Semaine dans l'annee : " & DatePart("ww" , dl, 2, 1)) 

DatePart 

La fonction DatePart renvoie un nombre de type Long correspondant a certaines 
valeurs interessantes deduites de la date. 

Dim dl As Date 
dl = "27/04/2006" 

MsgBox("Trimestre dans l'annee : " & DatePart("q" , dl)) 
MsgBox("Jour dans l'annee : " & DatePart("y" , dl)) 

MsgBox("Semaine dans l'annee : " & DatePart("ww" , dl, 2, 1)) 
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Les fonctions de conversion 

Les donnees etant de differents types, Basic nous permet de passer d'un type a l'autre 
grace a des fonctions de conversions implicites ou explicites. 



Les conversions automatiques de type 

Dans le but de simplifier la programmation, Basic effectue automatiquement des 
conversions de type. Ces conversions ont lieu lorsqu'une variable ou une expression 
d'un type A est affectee a une variable de type B, ou employee comme parametre 
d'un argument de type B. Elle peuvent aussi avoir lieu lors de revaluation d'une 
expression mathematique, et cela plusieurs fois. 

Basic essaie toujours de convertir, quels que soient les types simples impliques. Cer- 
taines conversions ne posent aucun probleme car le type final accepte toutes les 
valeurs possibles du type initial : 

• type Integer vers Long, 

• type Si ngl e vers Doubl e, 

• type Integer, Long, vers Currency, 

• type simple vers Vari ant. 

Quelques pertes apparaissent avec les arrondis necessaires pour convertir un reel en 
entier. En revanche, les resultats deviennent surprenants avec les types String et 
Boolean. 

Type Boolean vers type numerique 

La valeur True donne le resultat -1, la valeur Fal se donne le resultat zero. 

Type Boolean vers type String 

On obtientla chaine de caracteres "True" ou "False". 

Type numerique vers type Boolean 

La valeur zero donne un resultat Fal se, toute autre valeur donne un resultat True. 

Type numerique vers type String 

On obtient une chaine de caracteres representant la valeur decimale de la variable 
numerique (eventuellement apres normalisation, dans le cas d'un type Single ou 
Double). La representation utilise le separateur decimal de l'environnement linguis- 
tique d'OpenOffice (menu Outils>Options>Parametres linguistiques). 
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Type String vers type numerique 

Ici, le separateur decimal est toujours un point. Si la chaine de caracteres est inter- 
pretable comme un nombre, alors ce nombre est converti dans le type final ; sinon le 
resultat est zero. Basic recherche le nombre en balayant la chaine de gauche a droite, 
ce qui donne par exemple : 

dim si as string, dl as double 

si = " 15.3xyz 
dl = si 

print dl ' resultat : 15.3 

Type String vers type Boolean 

Si la chaine de caracteres s'evalue comme un nombre, le traitement est identique a 
celui d'un nombre ; si la chaine de caracteres est de longueur nulle, ou ne comporte 
que des espaces, le resultat est False ; dans les autres cas, une erreur est declenchee. 

L'ambiguTte de I'operateur + 

La plus grande difficulte survient avec I'operateur + qui est I'operateur d'addition de 
nombres, mais est aussi autorise comme operateur de concatenation de chaines. 
Nous vous avons conseille d'utiliser I'operateur & pour concatener les chaines, et nous 
allons voir pourquoi dans cette succession de tests de conversions : 

rem Code05-01.odt bibli : Standard Module4 
Option Explicit 

' danger des conversions implicites 
' et de I'operateur + a double usage 
Sub dangerConversionsO 
Dim dl As Long, d2 as Long 

Dim si As String, s2 As String, s3 As String, s4 As String 

si = "Victor " 
s2 = "Hugo" 
s3 = si & s2 

' Le + est interprets comme operateur de concatenation 
s4 = si + s2 

print "testl", s3, s4 ' memes resultats, operations identiques 

dl = 400 
d2 = 1000 
s3 = dl & d2 

' Le + est interprets comme operateur arithmetique 
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s4 = dl + d2 

print "test2", s3, s4 ' resultats differents ! 

' Basic interprete 1 'expression comme une chaine de caracteres 
s4 = "" + dl + d2 

print "test3", s3, s4 ' resultats identiques ! 

1 Basic interprete d'abord en numerique et finit en chaine 
s4 = dl + d2 +"" 

print "test4", s3, s4 ' resultats differents ! 

si = "100" 
s2 = "2000" 

dl = si + s2 ' attention : concatenation de chaines 
d2 = CLng(sl) + CLng(s2) ' addition de deux nombres 
print "test5", dl, d2 'resultats differents ! 

End Sub 

Le dernier test montre l'interet des conversions explicates, que nous listerons maintenant. 

Les conversions explicites 

Chaine de caracteres vers nombre 

La fonction Val convertit une chaine de caracteres representant un nombre en une 
valeur numerique de type Double. La chaine de caracteres doit etre un nombre 
exprime sous la forme anglo-saxonne, avec une virgule ou un espace comme separa- 
teur de milliers eventuel, et un point comme separateur decimal. 

La fonction Asc convertit le premier caractere d'une chaine en sa valeur numerique 
ASCII ou Unicode 16 bits. 

print AscC'A"), Asc("a"), Asc("a"), Asc("a"), Asc("€") 
65 97 224 226 8364 



Type numerique vers chaine de caracteres 

La fonction Chr est la transformation inverse de la fonction Asc. Elle renvoie une 
chaine d'un caractere dont la valeur ASCII ou Unicode correspond a la valeur nume- 
rique fournie en argument. Notez que cet argument est du type Long, et non 
Integer ; toute la gamme de valeurs entre 0 et 65 535 est utilisable. Certaines valeurs 
de caracteres non imprimables sont particulierement utiles : 

• Chr (13) correspond au caractere CR (anglais pour Retour de Chariot), souvent 
utilise pour afficher des messages sur plusieurs lignes. 
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• Chr(lO) correspond au caractere LF (anglais pour Nouvelle Ligne). 

• Chr(9) correspond au caractere de tabulation. 

La fonction Str et la fonction CStr renvoient toutes deux une chaine de caracteres 
correspondant a 1' expression en argument. Dans le cas d'un nombre, la chaine 
obtenue differe sur deux points : 

• le resultat de Str debute par un espace ; 

• pour representor le separateur decimal, Str utilise toujours le point alors que CStr 
utilise la valeur indiquee par l'environnement linguistique (une virgule pour fr-FR). 
Pour un nombre de type Currency, un bogue fait que CStr utilise lui aussi le point 
numerique (Issue 91121). 

Les fonctions Hex et Oct renvoient une chaine de caracteres correspondant respecti- 
vement au codage Hexadecimal ou Octal de la valeur numerique en argument. A 
propos, voici comment on ecrit en Basic un nombre en valeur hexadecimale et en 
valeur octale : 

Dim n As Long 

n = &HFF2 1 valeur hexadecimale FF2 

print n, hex(n) ' Verification 

n = &0752 ' valeur octale 752 

print n, oct(n) ' Verification 



La fonction Format 

La fonction Format renvoie une chaine de caracteres constituee a partir d'une donnee 
numerique et d'une chaine dite de formatage. Dans l'aide F1 de Basic, onglet Index, 
tapez Format et cherchez l'entree « Format, fonction ». Voici quelques exemples des 
possibilites. Certaines ne sont pas documentees dans l'aide F1 . 

rem Code05-01 . odt bibli : Standard Module3 
Option Explicit 

Sub exemplesFormat() 

Dim d As Variant, s As String, f As String 
d = 3.14 

MsgBox(Format(d, "+00.000"), 0, "Nombre de chiffres minimal") 
d = 1234567.5 

MsgBox(Format(d, "# ### ### ### ""km" ), 0, "Arrondi a Ventier") 

' format pour nombre positif ;negatif;nul 
f = "+# ##0.0; -#0; ""zero 
d = 12345.67 

MsgBox(d & " donne : " & Format(d, f ) , 0, "Nombre positif") 
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d = 0 

MsgBox(d & " donne : " & Format(d, f ) , 0, "Nombre nul") 
d = -12345.67 

MsgBox(d & " donne : " & Format(d, f ) , 0, "Nombre negatif") 
d = 1234567.596 

MsgBox(d & " donne : " & Format(d, "Currency"), 0, "Monetai re positif") 
d = -1234567.596 

MsgBox(d & " donne : " & Format(d, "Currency"), 0, "Monetai re negatif") 
d = 1234 ' on veut afficher : 1234 secondes 

MsgBox(Format(d , "0 secondes"), 0, "Affichage compl etement faux !") 
' les caracteres s, e, c, n, d peuvent etre interpretes ! 
MsgBox(Format(d , "0 \s\e\cond\e\s") , 0, "Affichage correct") 

d = Now 

s = Format(d, "NNN DD MMMM YYYY") 

s = s & chr(10) & Format(d, "QQ"", semaine ""WW") 

s = s & chr(10) & Format(d, "hh\h mm\mn ss\s\ec") 

MsgBox(s, 0, "Date et heure actuelles") 

End Sub 

Dans les chaines de format, le separateur decimal est toujours le point, alors que la 
chaine obtenue utilisera le separateur indique dans l'environnement linguistique 
(menu Outils>Options). On doit faire tres attention aux textes mis dans la chaine de 
formatage, car plusieurs caracteres peuvent etre interpretes par l'instruction Format. 
Pour eviter cela, on doit mettre un \ devant chaque caractere susceptible d'etre inter- 
prete. En general, dans une chaine de formatage, un texte doit etre entoure de 
guillemets ; comme il est lui-meme dans une chaine Basic, la syntaxe impose de 
redoubler chaque guillemet. 

Le format Currency ne sert qua obtenir une chaine monetaire a deux decimales, a 
partir d'un nombre de type autre que Currency. Une valeur de type Currency donne 
une chaine mal formatee (Issue 91121). 

Dans le chapitre 14 nous verrons, a la section « Une fonction Format plus puissante » 
comment utiliser toutes les possibilites de formatage qui existent pour une cellule de Calc. 

Conversions vers un type numerique 

Les fonctions suivantes convertissent une chaine de caracteres ou une valeur nume- 
rique en un type numerique specifique : 

• CDbl renvoie un Doubl e. Contrairement a la fonction Val , CDbl tient compte de la 
configuration locale : sur une version francaise (France) une chaine representant 
un nombre avec decimales doit comporter la virgule comme separateur decimal. 
Les separateurs de milliers ne sont pas acceptes. 
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• CSng renvoie un Si ngl e. Memes remarques que pour Doubl e. 

• CByte renvoie un Byte. 

• CInt renvoie un Integer. 

• CLng renvoie un Long. 

• CCur renvoie un Currency. 

• CDec renvoie un Decimal. Une chaine representant un nombre peut (actuellement) 
comporter indifferemment le point ou la virgule comme separateur decimal. 

Quand une fonction API renvoie un type Byte, la conversion automatique vers Basic 
donne (pour des raisons de compatibilite avec les anciens codages) une valeur de type 
Integer dans une plage de -128 a +127. Si on souhaite la convertir en type Byte, ce der- 
nier n'acceptant que des valeurs positives on doit n'utiliser que l'octet de poids faible : 

Dim a As Integer, b As Byte 
a = -37 

b = CByte(a and 255) 

Conversion d'un nombre reel vers un nombre entier 

Les fonctions Int et Fi x renvoient un nombre Doubl e dont la partie fractionnaire est 
nulle. La fonction Fi x renvoie un nombre dont la partie entiere correspond a la partie 
entiere du nombre en argument. La fonction Int renvoie un nombre arrondi a 
l'entier inferieur, que 1' argument soit positif ou negatif. 

Ces deux fonctions ne correspondent pas a l'arrondi classique. En revanche, la fonc- 
tion CLng et la fonction CInt arrondissent au nombre entier le plus proche. Elle diffe- 
rent seulement par le type du resultat, respectivement Long et Integer, et done la 
plage de valeurs admissibles en argument. La conversion implicite vers Long donne le 
meme resultat que CLng. 

Ce codage compare les fonctions sur differentes valeurs typiques : 

rem Code05-01 . odt bibli : Standard Module2 
Option Explicit 

Sub PartieEntiereQ 



Resultat - - > 


Fix 


Int 


CLng 


Impl 


comparer( 0) 


0 


0 


0 


0 


comparer( 0.00000000000001) ' 


0 


0 


0 


0 


comparer(-0. 00000000000001) ' 


0 


-1 


0 


0 


comparer( 7.00000000000001) ' 


7 


7 


7 


7 


comparer(-7. 00000000000001) ' 


-7 


-8 


-7 


-7 


comparer( 7.49999999999999) ' 


7 


7 


7 


7 


comparer( 7.5 ) ' 


7 


7 


8 


8 


comparer(-7. 49999999999999) ' 


-7 


-8 


-7 


-7 


comparer(-7. 5 ) ' 


-7 


-8 


-8 


-8 
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comparer^ 7.99999999999999) 
comparer(-7 . 99999999999999) 



7 
-7 



7 
-8 



8 
-8 



8 
-8 



End Sub 



Sub comparer(v As Double) 

Dim message As String, p As Long 

p = v' conversion implicite en Long 

message = "Nombre : " & n & chr(13) & _ 

"Fix : " & Fix(v) & chr(13) & "Int : " & Int(v) & chr(13) & 
"CLng : " & CLng(v) & chr(13) & "Implicite : " & p 

MsgBox(message) 

End Sub 



Changement de casse 

Le changement de casse consiste a transformer un caractere majuscule en caractere 
minuscule ou l'inverse. 

• La fonction Lease, pour Lower Case, renvoie une chaine de caracteres copiee de 
celle en argument, mais dont chaque caractere majuscule est remplace par l'equi- 
valent minuscule. Les autres caracteres sont simplement copies. 

• De meme, Ucase, pour Upper Case, effectue la mise en majuscules des caracteres 
minuscules. 

Ces conversions traitent correctement les caracteres accentues (a devient A). 

Conversions de date et heure 

Comme nous l'avons vu au chapitre 3, les dates (avec l'heure) sont codees en interne 
sous forme d'un nombre Doubl e appele dans le jargon OpenOffice.org serial number 
(anglais pour numero de serie). Plusieurs fonctions effectuent des conversions entre 
cette notation interne et les valeurs habituelles de date et heure. 

Fonctions renvoyant une date-heure interne 

• CDate(chaine) : l'argument est une chaine de caracteres representant une date et/ 
ou une heure. 



• CDate(nombre) : dans ce cas, l'argument est un nombre reel qui sera interprete 
comme une date interne. 

• DateSerial(annee, mois, jour). Si la relation jour-mois est incorrecte la date est 
corrigee : 1987 ,2,31 donne la date 1987 ,3,3. 

• TimeSerial (heure, minute, seconde). 



Les instructions de traitement I 

Chapitre 5 I 

• DateVal ue(chaine) : l'argument est une chaine de caracteres representant une 
date ; les heures-minutes-secondes sont ignorees. 

• TimeVal ue(chaine) : l'argument est une chaine de caracteres representant une 
heure precise. 

• CDateFromlso(chaine) : l'argument est une date de la forme annee, mois, jour, 
comme "2004123 1 " ou "2002/12/3 1 " . 

Fonctions prenant pour argument une date-heure interne 

• Day(date) renvoie le numero du jour dans le mois. 

• WeekDay(date) renvoie le rang du jour dans la semaine : dimanche=l, Lundi=2, 
jusqu'a Samedi=7. 

• Month(date) renvoie le numero du mois. 

• Yea r(date) renvoie 1' annee. 

• Hour(date) renvoie l'heure. 

• Mi nute(date) renvoie le nombre de minutes dans l'heure. 

• Second(date) renvoie le nombre de secondes dans la minute. 

• CDateToIso(date) renvoie une chaine de 8 caracteres comme "20041231". 

Conversion vers une valeur booleenne 

La fonction CBool recoit en argument une expression booleenne ou un nombre et 
renvoie une valeur booleenne. 



Test de contenu de variable 

Certaines de ces fonctions, listees au tableau 5-1, ont deja ete vues au cours du 
chapitre 3. Toutes prennent en argument une variable et renvoient la valeur boo- 
leenne True si le resultat du test est positif. Les fonctions concernant des objets 
UNO sont explicitees dans 1' annexe A. 

Tableau 5-1 Fonctions de test de contenu de variable 



IsArray 


Est-ce un tableau ? 


IsDate 


Est-ce une date valide ? 


IsEmpty 


La variable Van' ant a-t-elle la valeur Empty ? 


IsMi ssi ng 


L'argument du sous-programe est-il absent dans son appel ? 


IsNull 


La variable Van' ant ou Ob j ect a-t-elle la valeur Null? 
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Tableau 5-1 Fonctions de test de contenu de variable (suite) 



Fonction Test 


IsNumeri c 


La chame de caracteres en argument est-elle interpretable comme un nombre ? 


IsObject 


L'argument est-il un objet UNO ? 


IsUnoStruct 


L'objet en argument est-il une structure UNO ? 


Equa"IUnoObjects(vl, v2) 


Les deux variables v1 et v2 representent-elles le meme objet UNO ? 


HasUnoInterfaces 


L'objet UNO en premier argument offre-t-il toutes les interfaces indiquees en 
arguments ? 



Interface utilisateur : ecran, clavier 

MsgBox 

Cette fonction, qui possede plusieurs parametres optionnels, sert a afficher un texte 
dans une boite de dialogue standard, accompagne d'un ou plusieurs boutons permet- 
tant a l'utilisateur de fermer la fenetre de message. Elle est tres souvent utilisee car 
elle vous permet d'afficher une boite de dialogue simple tout a fait equivalente a 
celles produites par des applications professionnelles. 

Dans sa forme la plus simple, elle affiche un message avec un bouton OK et on n'uti- 
lise alors pas le resultat renvoye : 

MsgBox("Programme termine") 

L'aide en ligne ne decrivant pas exactement les possibilites, nous reproduisons ici 
celles qui sont effectivement utiles. 

La fonction MsgBox utilise trois parametres : 

1 le texte du message (chaine de caracteres), 

2 le type du message (optionnel, entier Integer), 

3 le titre de la boite (optionnel, chaine de caracteres) ; si cet argument est utilise, le 
type doit aussi etre utilise. 

Le texte du message peut s'afficher en plusieurs lignes en employant le caractere 
« Retour de Chariot » ou « Saut de ligne » pour changer de ligne, par exemple : 

Dim si As String 

si = "Ceci est un message" & chr(13) & _ 
"en plusieurs" & chr(13) & "lignes" 
MsgBox(sl) 
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Le type du message est la somme de trois valeurs de choix : 

1 le choix de l'ensemble de boutons (tableau 5-2) ; 

2 le choix d'une icone normalised (tableau 5-3), accompagnee du signal sonore qui 
lui est affecte par le systeme d'exploitation ; 

3 le choix du bouton par defaut (tableau 5-4). 

Le resultat de la fonction (tableau 5-5) permet de determiner quel bouton a ete 
actionne. Le tableau 5-2 indique aussi Taction resultant de la fermeture de la boite de 
dialogue (case X dans le coin de la fenetre). 

Tableau 5-2 Choix de l'ensemble de boutons 



0 


OK 






OK 


1 


OK 


Annuler 




Annuler 


2 


Interrompre 


Reessayer 


Ignorer 


(Inactif) 


3 


Oui 


Non 


Annuler 


Annuler 


4 


Oui 


Non 




Non 


5 


Reessayer 


Annuler 




Annuler 


Tableau 5-3 Choix de I'icone 




0 


aucune 




16 


X 


Message critique 


32 


7 


Question 


48 


! 


Avertissement 


64 


i 


Information 

Seul un bouton OK sera affiche 



Tableau 5-4 Choix du bouton par defaut 



Valeur Rang, de gauche a droite 


0 


le premier 


256 


le deuxieme 


512 


le dernier 


Tableau 5-5 Resultat renvoye par MsgBox 




1 


OK 


2 


Annuler 
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Tableau 5-5 Resultat renvoye par MsgBox (suite) 



Valeur Signification 


3 


Interrompre 


4 


Reessayer 


5 


Ignorer 


6 


Oui 


7 


Non 



Void un exemple recapitulatif, etudiez les messages et essayez des variantes. 



Dim r As Long 

r = MsgBox("Continuer le traitement ?", 3+32+256, "Modifier le texte") 
Select Case r 
Case 6 

MsgBox("Reponse : Oui") 
Case 7 

MsgBox("Reponse : Non") 
Case 2 

MsgBox("Reponse : Annuler") 
Case Else 

MsgBox("On ne devrait pas arriver ici !", 16, "Erreur de codage") 
End Select 



Print 

Le nom de cette instruction est impropre car elle ne sert pas a imprimer. Elle est sou- 
vent utilisee pour afficher un message servant a la mise au point des macros. En effet, 
ce message comporte les boutons OK et Annuler ; l'activation du bouton Annuler (ou la 
fermeture de la boite) avorte l'execution de la macro, ce qui peut etre tres utile pour 
se sortir d'une « boucle infernale ». 

Si le message comporte des caracteres « Retour de Chariot », Basic traite chaque 
ligne du message comme un appel a Pri nt. 

L'instruction Print accepte plusieurs arguments avec diverses possibilites d'affichage 
expliquees dans l'aide F1 ; rechercher dans l'index « Instruction;Print ». L' argument 
optionnel Fi 1 eName n'est pas utilise pour un affichage. 

InputBox 

L'instruction InputBox est un moyen simple et rustique de demander une information 
a l'utilisateur. Cette information est recuperee sous forme d'une chaine de caracteres. 
Le texte d'invite peut comporter jusqu'a trois lignes, en utilisant chr(13) comme 
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retour a la ligne. Si l'utilisateur a annule la boite de dialogue, on recupere un texte de 
longueur nulle, ce qui peut etre ambigu si c'est une reponse acceptable. Les dimensions 
de la boite sont fixes, ce qui n'est pas vraiment esthetique. Void un exemple : 

Dim r As String, n As Double 

r = InputBox("Tapez un nombre" , "Entree des donnees", 17) 
if Len(r) = Othen 

MsgBox("Reponse : annuler; ou bien un texte vide") 
elseif IsNumeric(r)then 

1 converti r dans le type numerique attendu, ici : Double 
n = CDbl(r) 

MsgBox("Votre nombre est : " & n) 
el se 

MsgBox("Votre texte est : " & r) 
end if 

Nous devons verifier si la reponse est bien un nombre, sinon la conversion en Doubl e 
pourrait declencher une erreur. Pour avoir plus de possibilites, il faut utiliser un veri- 
table dialogue, comme nous l'expliquons au chapitre 11. 

L'aide Fl sur InputBox est incorrecte concernant le positionnement : il est relatif au 
coin haut/gauche de la fenetre OpenOffice courante ; et quand les arguments de posi- 
tionnement sont absents, la boite est centree dans la fenetre OpenOffice courante. 

Codage des couleurs 

Beaucoup d'elements sont colores, comme des caracteres de texte, le fond d'une cel- 
lule, le contour et le fond des dessins. Nous apprendrons dans d'autres chapitres a les 
manipuler et a changer leur couleur. 

OpenOffice.org gere les couleurs sur 24 bits, ce qui nous offre 16 777 216 nuances 
possibles, du noir au blanc en passant par tout l'arc-en-ciel avec de multiples lumino- 
sites. Une couleur est definie a partir des trois couleurs fondamentales : Rouge, Vert, 
Bleu. L'intensite de chacune d'entre elles est definie par un nombre sur 8 bits, don- 
nant une plage de valeurs de 0 a 255 ; l'absence de cette couleur correspond a la 
valeur nulle, et l'intensite augmente avec la valeur. 

Une couleur particuliere peut etre memorisee dans une variable de type Long. La 
fonction RGB renvoie la valeur de couleur correspondant aux trois couleurs fondamen- 
tales qui la constituent, dans l'ordre : Rouge (anglais Red), Vert (anglais Green), Bleu 
(anglais Blue). 

Dim couleur As Long 

couleur = RGB(100, 220, 187) ' rouge vert bleu 
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Vous pouvez visualiser la nuance correspondante en utilisant la palette de couleurs 
disponible par le menu Outils>Options>OpenOffice.org>Couleurs (figure 5-1, malheu- 
reusement en noir et blanc). 



Figure 5-1 

La palette de couleurs 




Chaque fonction Red, Green, Blue extrait une des couleurs fondamentales consti- 
tuant une nuance de couleur. Une couleur fondamentale peut etre memorisee dans 
une variable Integer (ou Long a fortiori). 

print Red(couleur) , Creen(couleur) , Bl ue(coul eur) 

Signalons que le chapitre 14 montre comment, grace a l'API, vous pouvez connaitre 
les couleurs disponibles dans la palette geree par OpenOffice.org. 



Traitement des fichiers 

Syntaxe des adresses de fichiers 

La syntaxe des adresses de fichiers ou de repertoires differe selon les systemes 
d'exploitation. Or vos macros peuvent etre executees sur une version OpenOffice.org 
installee sur MS-Windows, Linux/Unix ou Mac OS. 

La fonction ConvertToURL renvoie une adresse URL equivalente a l'adresse au format 
natif du systeme d'exploitation sur lequel fonctionne votre programme. La conver- 
sion inverse est effectuee par ConvertFromURL. Utilisez toujours ces fonctions, car si 
l'adresse systeme comporte des caracteres nationaux, leur representation URL est un 
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codage derive de UTF-8. Pour les langages autres que Basic, il est possible d'ecrire 
des routines equivalentes en utilisant un service de l'API (voir l'annexe A). 

La fonction getPathSeparator, non decrite par l'aide F1 mais utilisee dans des exem- 
ples, renvoie le caractere separateur propre au systeme d'exploitation utilise, soit \ 
pour MS-Windows et / pour les systemes Unix. Ceci vous permet d'ajouter facile- 
ment un nom de fichier a un chemin de repertoire. 

adrFichier = chemin & getPathSeparator & "toto.bin" 

Gestion de fichiers 

Ces instructions et fonctions s'appliquent sur des fichiers qui ne sont pas ouverts. 

Les instructions ou fonctions suivantes ne posent pas de probleme particulier d'utili- 
sation et sont decrites clairement dans l'aide F1 : 

• MkDi r cree un repertoire. 

• RmDi r supprime un repertoire. 

• Fi 1 eExi sts renvoie True si un fichier ou un repertoire existe. 

• Fi 1 eDateTi me renvoie la date-heure du fichier. 

• Fi 1 eLen renvoie la taille du fichier. 

• Fi 1 eCopy effectue une copie du fichier. 

• Name renomme le fichier ou le repertoire. 

• Ki 1 1 detruit le fichier ou le repertoire. 

Les fonctions ChDrive, CurDi r et ChDi r, bien que documentees, ne sont plus prises 
en charge. Elles n'ont plus d'utilite dans un systeme d'exploitation moderne. Les 
programmeurs VBA ont pour habitude d'employer le repertoire dans lequel se trouve 
le fichier sur lequel ils travaillent ; ceci peut etre deduit de la propriete URL du docu- 
ment, qui donne l'adresse complete de son fichier (voir le chapitre 7, section « Les 
proprietes du document »). 

Abordons maintenant les instructions plus complexes. 

Explorer un repertoire 

La fonction Di r sert a explorer un repertoire pour trouver les sous-repertoires ou 
fichiers qu'il contient. La description de cette fonction dans l'aide F1 est correcte, 
mais l'exemple contient des erreurs. 
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Void un premier exemple qui liste les sous-repertoires d'un repertoire donne. 

rem Code05-03 . odt bibli : Standard Modulel 
Option Explicit 

Sub Li sterSousRepertoi reslRepertoi re() 
Dim RepBase As String, unRep As String 
' terminer le nom du repertoire avec le separateur 
RepBase = InputBox("Repertoi re a explorer") 
unRep = Dir(RepBase, 16) 
Do While Len(unRep) > 0 
print unRep 

unRep = Dir' sous-repertoire suivant 
Loop 
End Sub 

Le chemin du repertoire est ecrit avec la syntaxe du systeme d'exploitation ou avec la 
syntaxe URL. II doit se terminer par un separateur (caractere \ pour MS-Windows, 
caractere / pour Linux et syntaxe URL). Vous remarquerez 1' existence des pseudo- 
repertoires . et . . qui representent respectivement le repertoire lui-meme et le reper- 
toire parent. En general, ces deux repertoires doivent etre ignores avec un test i f . 

Le deuxieme exemple liste les fichiers ordinaires qui se trouvent dans un repertoire 
donne. 

rem Code05-03 .odt bibli : Standard Module2 
Option Explicit 

Sub ListerFichierslRepertoi re() 

Dim RepBase As String, unFich As String 

' terminer le nom du repertoire avec le separateur 

RepBase = InputBox("Repertoi re a explorer") 

unFich = Dir(RepBase & "*", 0) ' chercher tous les fichiers 

Do While Len(unFich) > 0 

print unFich ' utilisez le bouton Annuler pour stopper ! 

unFich = Dir' fichier suivant 

Loop 
End Sub 

La fonction Di r renvoie le nom complet du fichier, sans son repertoire. Lorsque la 
recherche ne trouve rien, elle renvoie une chaine de longueur nulle. En changeant la 
chaine de recherche, vous pourriez par exemple rechercher tous les fichiers d'une 
extension particuliere. 
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Explorer un arbre de repertoires 

Pour explorer un arbre contenant des sous-repertoires imbriques et des fichiers dans 
chacun d'eux, il est quasiment indispensable d'employer la recursivite. Ceci est pos- 
sible avec OOoBasic, mais nous allons avoir une difficulte car la fonction Di r n'est 
pas utilisable de maniere recursive. 

Le codage suivant presente la methode generale. Pour l'exemple, nous nous conten- 
terons d'afficher chaque fichier et chaque sous-repertoire repere. 

rem Code05-03 . odt bibli : Standard Module3 
Option Explicit 

Sub ExplorationRecursiveO 
Dim URLracine As String 

URLracine = convertToURL("c : \") 
explorerFichiers(URLraci ne) 
End Sub 



Sub explorerFichiers(ceRepertoi re As String) 
Dim f2 As String 

f2 = Di r(ceRepertoi re & 0) ' chercher tous les fichiers 

Do While Len(f2) > 0 

print ceRepertoire & f2 

f2 = Di r ' fichier suivant 
Loop 

1 appel recursif ! 
explorerRepertoires(ceRepertoi re) 
End Sub 



Sub explorerRepertoires(ceRepertoi re As String) 

Dim d2 As String, x As Long 

Dim nouvRep As String, listeRep As String 

d2 = Di r(ceRepertoi re, 16) ' chercher les sous-repertoires 
' memoriser les sous-repertoires car Di r n'est pas recursif 
Do While Len(d2) > 0 

if (d2 <> ".") and (d2 <> "..") then 
listeRep = listeRep & d2 & "*" 

end if 

d2 = Di r ' sous-repertoire suivant 
Loop 
x = 1 

d2 = elmtRepSuiv(listeRep, x) 
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Do While Len(d2) > 0 

nouvRep = ceRepertoi re & d2 & "/" 

print nouvRep 

' appel recursif ! 

explorerFichiers (nouvRep) 

d2 = elmtRepSuiv(listeRep, x) 

Loop 
End Sub 

1 renvoi e 1 'element suivant et modifie debut 

Function elmtRepSuiv(listElements As String, debut As Long) As String 
Dim x2 As Long 

x2 = InStr(debut, 1 i stEl ements , "*") 
if x2 = 0 then 

elmtRepSuiv = "" 
el se 

elmtRepSuiv = Mi d(l i stEl ements , debut, x2 -debut) 

debut = x2 +1 
end if 
End Function 

Initialisez la variable URLracine avec le nom d'une arborescence interessante, et 
n'oubliez pas de mettre un \ a la fin. 

La macro explorerFichiers recherche tous les fichiers du repertoire en argument. Ici, 
l'utilisation de Di r est identique a ce que nous avons vu. Quand tous les fichiers ont ete 
trouves, la macro lance l'exploration des sous-repertoires du repertoire courant. 

Dans la macro explorerRepertoi res, nous sommes obliges de recourir a une astuce. 
En effet, pour chaque sous-repertoire que nous trouverons, nous allons lancer la 
recherche de fichiers. Comme cette derniere utilise aussi la fonction Di r, nous ne 
pouvons pas etre alors en train d'executer une recherche avec Di r. Nous allons done 
d'abord rechercher tous les sous-repertoires et les memoriser. 

Pour effectuer la memorisation des noms de sous-repertoires, nous hutilisons pas un 
tableau de Stri ng, car il faudrait le redimensionner en cours de recherche avec l'option 
Preserve, ce qui ralentirait l'algorithme. Nous avons prefere memoriser tous les noms 
dans un seul Stri ng, en les separant par un caractere * qui ne peut etre utilise dans un 
nom de sous-repertoire. Nous avons de la place, car une chaine peut contenir 
65 535 caracteres. En explorant le repertoire c : \ d'un disque MS-Windows bien 
encombre, la variable 1 i steRep ha pas depasse 3,5 % de la taille maximale possible. 

Nous recuperons ensuite ces noms un par un avec la fonction elmtRepSuiv. Pour 
chaque nom, apres affichage, nous lancons la recherche des fichiers de ce sous- 
repertoire : ici commence la recursion. Elle se terminera avec l'epuisement des sous- 
repertoires de chaque sous-repertoire. 
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Lire et modifier des attributs de fichier ou repertoire 

La fonction GetAttr sert a lire les attributs d'un fichier ou d'un repertoire. L'instruc- 
tion SetAttr permet de les modifier. 

Les attributs indiques dans l'aide en ligne ne sont pas tous utilisables. Seules ces 
valeurs ont pu etre verifiees sous MS-Windows XP : 

• 0 : fichier sans attribut particulier ; 

• 1 : fichier en lecture seule ; 

• 2 : fichier cache ; 

• 3 : fichier cache et en lecture seule ; 

• 16 : repertoire sans attribut particulier ; 

• 18 : repertoire cache. 

Ecrire et lire un fichier 

Lire ou ecrire un fichier se fait toujours en trois etapes : 

1 Ouvrir le fichier grace a l'instruction Open. 

2 Ecrire avec Print ou Write ou Put, ou lire avec Get ou Input. 

3 Fermer le fichier avec CI ose. 

L'aide F1 est malheureusement assez obscure dans ses descriptions et exemples. Nous 
allons essayer de clarifier ces concepts. 

Fichier texte 

Le codage suivant ecrit un fichier en texte simple (sans formatage). 

rem Code05-03 . odt bibli : LireEcrire Modulel 
Option Explicit 

1 adaptez le nom et le repertoire a votre systeme 

Public Const nomFichier = "C:\Docs 0pen0ffice\essai001.txt" 

Sub Ecri reFi chi erTexteVIO 
Dim fl As Integer 
Dim OuiNon As Boolean 

OuiNon = True 

fl = FreeFile' obtenir un numero de fichier ouvert 

Open nomFichier For Output As #fl 

Print #fl, "Ceci est un texte." 

Print #fl ' ligne vide 
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Print #fl, "Troisieme ligne du texte ", 12345, OuiNon 
Close #fl 
End Sub 

Nous definissons une constante contenant le nom et le chemin d'acces au fichier a 
ecrire. Cette constante est publique car nous l'utiliserons dans d'autres modules. Nous 
aurions aussi bien pu employer une variable. Pour ecrire ou lire un fichier, nous avons 
besoin d'un « numero de canal d'entree/sortie » qui nous est renvoye par la fonction 
FreeFi 1 e. II servira ensuite a preciser a Basic le fichier concerne par chaque instruction 
d'entree/sortie (car nous pourrions ouvrir plusieurs fichiers simultanement). 

L'instruction Open comporte de multiples variantes pour ses arguments. Ici, nous deman- 
dons d'ouvrir en ecriture (en anglais, For Output) le fichier dont le chemin d'acces est 
indique par la variable monFi chi er ; nous precisons notre numero de canal, qui doit etre 
ecrit precede du caractere diese. L'argument For Output provoque l'effacement et la 
recriture d'un fichier pre-existant du meme nom, sans aucun avertissement. 

Les instructions suivantes ecrivent chacune une ligne de texte dans le fichier. Nous 
utilisons l'instruction bien connue Print, mais avec une syntaxe differente : le pre- 
mier argument est le numero de canal d'entree/sortie precede du caractere diese. 
Chaque Print ecrit une ligne de texte dans le fichier, completee par une sequence de 
fin de ligne. L'instruction CI ose ferme le fichier. Vous pouvez maintenant le relire 
dans un editeur de textes. 

L'encodage utilise par OOoBasic est celui du systeme d'exploitation (Windows 1252 
sous MS-Windows en France), ainsi que la sequence de fin de ligne (CR, LF sous 
MS-Windows, LF sous Unix/Linux). Les fichiers ainsi ecrits ne sont done pas lisi- 
bles par un autre systeme d'exploitation, aussi il est preferable d'utiliser l'API pour 
ecrire ou lire un fichier texte (voir chapitre 7 section « Importer, exporter du texte 
pur », et chapitre 14 section « Gerer les fichiers depuis l'API ». 

Nous allons relire ligne par ligne ce fichier de texte avec la macro suivante. 

rem Code05-03 . odt bibli : LireEcrire Module2 
Option Explicit 

Sub Li reFichierTexteVersionlO 

Dim fl As Integer, nomFichier As String 

Dim uneLigne As String 

fl = FreeFile ' obteni r un numero de fichier ouvert 
Open nomFichier For Input As #fl 
Do While not Eof(fl) 

Line Input #fl, uneLigne 

print uneLigne 
Loop 
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Close #fl 
End Sub 

Nous ouvrons le fichier en lecture (en anglais, For Input). Une erreur se declenchera 
si ce fichier n'existe pas. 

La fonction Eof renvoie True tant qu'il reste au moins une information a lire dans le 
fichier. Notez qu'ici, on ne met pas de diese devant le numero de reference. 

L'instruction Line Input recupere une ligne complete dans la variable chaine de 
caracteres. Elle est utile pour lire le contenu exact d'un fichier texte quelconque. 
Nous affichons la ligne lue avec une instruction print dans sa syntaxe ordinaire. 
Notez que la sequence de fin de ligne n'apparait pas dans la chaine obtenue. 

Fichier texte pour sauver des donnees 

Reprenons l'exemple du Modulel en remplacant les instructions Print par des ins- 
tructions Write. 

rem Code05-03 . odt bibli : LireEcrire Module3 
Option Explicit 

Sub Ecri reFi chi erTexteV2 () 
Dim fl As Integer 
Dim OuiNon As Boolean 

OuiNon = True 

fl = FreeFile ' obteni r un numero de fichier ouvert 
Open nomFichier For Output As #fl 
Write#fl, "Ceci est un texte." 

Write #fl, "" ' ligne vide 

Write #fl, "Troisieme ligne du texte ", 12345, OuiNon 
Close #fl 
End Sub 

Remarquez avec le deuxieme Wri te que nous avons ajoute un argument en plus du 
numero de canal, contrairement a la syntaxe indiquee par l'aide en ligne. 

Relisez maintenant le fichier texte (avec un editeur ou par la macro du Module2). Le 
contenu vous surprendra probablement : 

"Ceci est un texte." 

"Troisieme ligne du texte ", 12345 , #True# 

En fait, Basic ecrit un texte de maniere a pouvoir le relire en reconnaissant des ele- 
ments Stri ng ou des valeurs, separes par des virgules. Ce n'est pas un texte ordinaire 
mais un moyen de stocker des donnees. 
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Supposons maintenant que nous commissions la structure du fichier a lire, mais pas 
son contenu : nous savons seulement qu'il se compose d'un texte, puis un texte, puis 
un texte, puis un nombre, puis une valeur booleenne. Voici comment recuperer les 
valeurs correspondantes : 

rem Code05-03 .odt bibli : LireEcrire Module4 
Option Explicit 

Sub Li reFichierTexteVersion2() 
Dim fl As Integer 

Dim unTexte As String, unNombre As Long, unBool As Boolean 

fl = FreeFile ' obteni r un numero de fichier ouvert 

Open nomFichier For Input As #fl 

Input #fl, unTexte 

print unTexte 

Input #fl, unTexte 

print unTexte 

Input #fl, unTexte, unNombre, unBool 

print unTexte 

print unNombre, unBool 

Close #fl 

End Sub 

Les instructions print montrent que nous recuperons bien les informations origi- 
nales, sans qu'elles soient modifiees par les caracteres de delimitation qui se trouvent 
dans le fichier. Evidemment, si la structure du fichier differe quelque peu de ce qu'on 
attend, les informations ne seront pas correctement recuperees et une erreur d'execu- 
tion pourra se produire. 

Fichier binaire a acces direct 

Le codage suivant va creer et utiliser un fichier binaire a acces direct (il ne s'agit plus 
d'un fichier texte). Dans un tel fichier, chaque enregistrement occupe un meme 
nombre d'octets. Linteret est de disposer de l'equivalent d'un tableau unidimen- 
sionnel comportant un tres grand nombre d'elements, et dans lequel l'acces a un ele- 
ment quelconque ne necessite pas d'avoir lu tous les elements qui le precedent. 

rem Code05-03 . odt bibli : LireEcrire Module5 
Option Explicit 

Sub Ecri reRel i reFi chi erAccesDi rect() 
Dim fl As Integer 

Const nomFichier = "C:\Docs 0pen0ffice\essai002.bin" 
Dim uneValeur As Double, n As Long 
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fl = Free File 

' chaque enregi strement contiendra un Double = 8 octets 
Open nomFichier For Random Access Write As #fl Len=8 
uneValeur = 2 

for n = 1 to 100 ' ecrire les puissances de 2 successives 

Put #fl, , uneValeur 

uneValeur = uneValeur * 2 
next 

Close #fl 

' relecture du fichier 
fl = FreeFile 

Open nomFichier For Random Access Read As #fl Len=8 

Get #fl, 10, uneValeur ' chercher 2 puissance 10 
print uneValeur 

Get #fl, 3, uneValeur ' chercher 2 puissance 3 
print uneValeur 

Get #fl, 32, uneValeur ' chercher 2 puissance 32 
print uneValeur 

Get #fl, 100, uneValeur ' chercher 2 puissance 100 
print uneValeur 
Close #fl 
End Sub 

L'instruction Open est utilisee avec le parametre For Random qui indique un acces 
direct, suivi du parametre Access Write precisant que seule l'ecriture de fichier sera 
utilisee. Le parametre Len indique la taille de chaque enregistrement ; ici, nous vou- 
lons stocker des nombres Double, qui occupent 8 octets chacun. 

Dans la phase d'ecriture, nous utilisons l'instruction Put pour ecrire chaque enregis- 
trement. La deuxieme virgule separe un parametre inutilise, le numero 
d'enregistrement : les enregistrements sont ecrits ici successivement. 

Nous relisons ensuite le fichier en utilisant faeces direct : le deuxieme parametre de 
l'instruction Get precise le numero de l'enregistrement a rechercher. Si vous con- 
naissez par coeur vos puissances de deux, vous pourrez verifier que les valeurs obte- 
nues sont correctes... 

Lacces direct est aussi possible en ecriture, mais seulement sur des enregistrements 
deja ecrits. Pour le demontrer, placez cette instruction juste avant la fermeture du 
fichier en ecriture : 

| Put #fl,32, 111111111 

La relecture vous renverra bien cette valeur pour l'enregistrement 32. 
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Fichier binaire pur 

Le parametre For Binary de l'instruction Open sert, en principe, a ecrire des fichiers 
binaires de contenu quelconque. Cependant, des essais nous ont montre que, pour 
diverses raisons, cette fonctionnalite est inutilisable. Utilisez plutot le service 
Si mpl eFi 1 eAccess de l'API, il permet lui aussi de manipuler des fichiers, et particu- 
lierement les fichiers binaires. Nous aborderons ce sujet dans le chapitre 14. 

Autres instructions pour fichiers ouverts 

Les fonctions et instructions suivantes sont utilisables sur des fichiers ouverts. Elles 
ne presentent pas de difficulte particuliere, aussi nous vous renvoyons a la lecture de 
l'aide F1 : 

• Reset ferme tous les fichiers en cours ; elle est utile dans les traitements d'erreur. 

• Loc et Seek concernent la position courante dans le fichier traite. 

• Eof indique si la lecture est arrivee en fin de fichier. 

• Lof renvoie la taille du fichier. 

• FileAttr renvoie le mode d'ouverture du fichier, ou son handle (information qui 
ne concerne que les specialistes). 



Fonctions systeme 

La fonction Envi ron permet de recuperer la valeur d'une variable d'environnement. II 
n'existe malheureusement pas de moyen pour modifier une variable d'environnement 
par Basic. 

L'instruction Beep sert a emettre un signal sonore. Sous MS-Windows, il s'agit du 
son par defaut. 

La fonction GetSolarVersion peutvous aider a determiner la version exacte d'Open- 
Office.org sur laquelle la macro s'execute. 

La fonction GetCUIType renvoie un nombre indiquant la famine a laquelle appartient 
le systeme d'exploitation sur lequel la macro s'execute : 1 pour MS-Windows, 3 pour 
Mac OS, 4 pour Unix. 

Les fonctions TwipsPerPixelX et TwipsPerPixelY servaient a convertir en pixels les 
dimensions d'elements de boites de dialogue. Ce systeme de mesure n'est plus utilise. 
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Lancer un programme externe 

L'instruction Shell permet de lancer l'execution d'un autre programme. Sous 
MS-Windows, il est preferable de convertir l'adresse du programme au format URL, 
grace a la fonction ConvertToURL, car les chemins comportant des espaces ou autres 
caracteres non alphabetiques ne sont pas reconnus. Quant a l'argument du programme, 
sous MS-Windows il est necessaire de l'encadrer de guillemets s'il comporte des 
espaces. Sous OOoBasic, redoubler chaque guillemet dans une chaine de caracteres. 

Dim programme As String, adrFich As String 
programme = convertToURL( 

"C:\Program Fi 1 es\Wi ndows NT\Accessoires\wordpad.exe") 
adrFich = "C:\Docs OpenOff i ce\el eves\notes joelle.txt" 
Shell (programme, 1, & adrFich & "' ) 

Les applications internes de MS-Windows n' existent pas sous forme d'un fichier exe- 
cutable, done Shell ne les trouvera pas. Le probleme est contourne en ecrivant un 
fichier batch .bat qui lance le programme, et en lancant le batch par Shell. Cet 
exemple de fichier batch ecrit la version exacte de MS-Windows dans un fichier texte. 

Ver >version.txt 

Un autre besoin est, par exemple, d'afficher un document HTML avec le navigateur 
assigne par defaut a ce type de fichier. Ceci n'est pas realisable par Shel 1 , mais necessite 
une autre methode qui utilise l'API d'OpenOffice.org. Nous la verrons au chapitre 14. 



Conclusion 

OooBasic propose de nombreuses fonctionnalites intrinseques. Du traitement des 
chaines de caracteres a la manipulation des fichiers, toutes ces instructions concou- 
rent a 1' elaboration de programmes de plus en plus complets. 

Le chapitre suivant expose comment traiter les erreurs apparaissant en cours d'execu- 
tion dans nos programmes parfois longs et complexes. 
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Nous allons traiter ici de la maniere d'ecrire des programmes Basic robustes, car 
capables de reagir raisonnablement face a un evenement anormal. Le programme 
pourra ainsi afficher un message comprehensible pour l'utilisateur et fermer correcte- 
ment les documents qu'il etait en train de traiter, ou encore demander a l'utilisateur 
s'il souhaite continuer le traitement ou l'arreter. 

Nous verrons enfin que ce meme principe peut etre utilise pour simplifier certains 
codages. 

Evitez les erreurs d'inattention 

Verifiez la syntaxe de chaque module que vous avez ecrit ou modifie. II suffit de cli- 
quer sur le bouton Compiler dans l'EDI. Faites-le pour chaque module modifie, car 
seul celui affiche par l'EDI est analyse. Vous pouvez egalement executer dans la 
meme bibliotheque une macro qui ne fait rien, car cela force Basic a compiler tous 
ses modules : 

Sub force rCompil 
End Sub 
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Si vous utilisez des instructions complexes, ou des notations pointees en cascade, il 
devient difficile de trouver la raison de l'erreur d'execution. Decomposez l'instruction 
en plusieurs instructions successives, et reperez celle qui declenche l'erreur. 
Remontez ensuite en verifiant chaque variable ou valeur utilisee. 

Beaucoup d'erreurs sont dues a une faute d'orthographe. Relisez, relisez une 
deuxieme fois, passez a autre chose, revenez-y et relisez encore. 

Respectez la casse (distinguez les majuscules des minuscules) des caracteres pour les 
arguments en chaine de caracteres, ainsi que pour les constantes API. Ce code est un 
exemple typique : 

DescrTri (0) . Name = "SortFields" ' Attention a la casse ! 
DescrTri (0) . Val ue = ConfigTn'O 

DescrTri (1) . Name = "Orientation" ' Attention a la casse ! 
' Constante API sur la ligne suivante, attention a la casse ! 
DescrTri (1) .Val ue = com. sun. star. table. TableOrientation. ROWS 
DescrTri (2) .Name = "Contai nsHeader" ' Attention a la casse ! 
DescrTri (2) .Val ue = true 



Le mecanisme d'interception d'erreur 

Le principe de traitement d'une erreur d'execution est de derouter 1' execution vers 
une adresse particuliere ou se trouve un codage qui va analyser l'erreur et reagir de 
facon adequate. On utilise pour cela une instruction tres similaire au GoTo, dont nous 
avons dit grand mal au chapitre 4. Nous expliquerons ses multiples possibilites avec 
des exemples volontairement simples. 

Un exemple typique 

rem Code06-01.odt bibli : Erreurs Modulel 
Option Explicit 

Sub TraitementErreurVIO 
Dim chemFich As String 

Do 1 boucler jusqu'a ce que 1 ' uti 1 i sateur reponde Annul er 
chemFich = InputBox("Chemi n du fichier ?") 
if Len (chemFi ch) = 0 then Exit Do 

On Error CoTo errFich' proteger les instructions suivantes 
MsgBox "Taille du fichier " & FileLen(chemFich) 
On Error CoTo 0' supprimer le traitement d'erreur 
MsgBox "OK" 
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Loop 

Exit Sub' terminaison d'execution du sous-programme 
errFich : 

MsgBox("Ce fichier n'existe pas", 16) 
' reprendre 1 'execution apres 1 ' i nstructi on en faute 
Resume Next 
End Sub 

Cet exemple typique consiste a afficher la taille (en octets) cl'un fichier indique par 
l'utilisateur. N'hesitez pas a l'executer en pas-a-pas dans l'EDI. Repondez une pre- 
miere fois avec un fichier existant : la boucle s' execute en sequence et les deux ins- 
tructions On Error semblent ne rien faire de parti oilier. 

Donnez maintenant une reponse incorrecte. Au lieu d'executer l'instruction Msg Box 
de la boucle, c'est le MsgBox situe a la suite de l'etiquette errFi ch qui est execute. En 
effet, l'instruction precedente stipule qu'en cas d'erreur (toute erreur), le programme 
doit aller a cette etiquette. L'instruction Resume Next force 1' execution a reprendre a 
la suite de celle qui avait cause une erreur. 

L'instruction On Error GoTo 0 a pour effet de revenir au traitement d'erreur par 
defaut (Basic affiche un message et stoppe le programme). Si elle n'existait pas, le 
traitement d'erreur mis en place resterait en vigueur pour les instructions suivantes. 
Supposez qu'une autre erreur se produise, par exemple une division par zero dans un 
calcul : l'execution serait deroutee de nouveau a l'etiquette errFich et un message 
sans rapport avec l'erreur s'afficherait. Reduisez done la portee de votre traitement 
d'erreur au codage concerne. 



PlEGE Instruction Resume 

Si vous utilisez l'instruction Resume toute seule, sans argument, l'instruction en faute sera re-executee. 
Cette faculte est parfois utile. Cependant, si vous n'avez pas prevu le traitement en consequence, vous 
entrerez dans une boucle infernale. 

Consequence d'une instruction non executee 

Comme nous l'avons constate, l'instruction declenchant une erreur n'est pas exe- 
cutee. Supposons que nous ayons utilise une variable intermediate (de type Long) : 

longFich = FileLen(chemFich) 
MsgBox longFich 



Dans ce cas, au retour du traitement d'erreur, la variable longFich n'aurait pas recu 
de valeur ; ou plus exactement, elle garderait la valeur quelle possedait avant l'ins- 
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truction, eventuellement provenant du tour de boucle precedent. Ceci peut induire 
des erreurs logicielles dans la suite du traitement. Vous devez penser a cet aspect dans 
votre traitement d'erreur. Le prochain exemple nous donnera une solution. 

Reprise du traitement a un autre endroit 

Reprenons 1' exemple precedent en ajoutant une autre instruction qui affiche les attri- 
buts du fichier. 

rem Code06-01 . odt bibli : Erreurs Module2 
Option Explicit 

Sub TraitementErreurV2() 

Dim chemFich As String, repertoire As String 

Do ' boucler jusqu'a ce que 1 ' uti 1 i sateur reponde Annuler 
chemFich = InputBox("Chemi n du fichier ?") 
if Len(chemFi ch) = 0 then Exit Do 

On Error CoTo errFich ' proteger les instructions suivantes 
MsgBox "Taille du fichier " & FileLen(chemFich) 
1 - - autres instructions liees au fichier - - 
MsgBox "Attributs du fichier : " & CetAttr(chemFi ch) 
suitel: 

On Error CoTo 0 ' supprimer le traitement d'erreur 
1 - - autres instructions non liees au fichier - - 
MsgBox "OK" 
Loop 

Exit Sub ' terminaison d'execution du sous-programme 
errFi ch : 

MsgBox("Ce fichier n'existe pas", 16) 
' eviter la poursuite du traitement normal 
Resume suitel' reprendre a 1 'etiquette suitel 
End Sub 

Si nous avions un traitement d'erreur Resume Next, l'affichage des attributs declenche- 
rait une nouvelle erreur. II est certain qu'en cas d'erreur sur la premiere instruction, les 
autres utilisant chemFich ne signifient plus rien. L'instruction Resume suitel nous 
permet de reprendre a un endroit plus approprie de notre codage. 

Nous avons ici une solution, mais aussi une source d'ennuis si nous effectuons des 
sauts un peu n'importe ou dans le codage, car Basic executera aveuglement le saut, 
meme si cela conduit a un bouclage. Pour eviter les programmes « plats de 
spaghetti » suivez ces conseils : 

• Limitez la taille de vos sous-programmes. 

• Ecrivez d'abord le fonctionnement sans erreur du sous-programme, termine par 
un Exit Sub (ou Exit Function). 
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• Placez en fin de sous-programme les traitements d'erreurs. 

• Faites des traitements d'erreur simples. 

• Relisez attentivement votre programme en executant mentalement chaque cas 
d'erreur, y compris la reprise du cours normal d'execution apres son traitement. 



Vous pouvez avoir l'idee de faire un traitement d'erreur se terminant par un simple 
CoTo pour continuer 1' execution, sans executer une instruction Resume. C'est une 
mauvaise idee, car l'instruction Resume sert aussi a desactiver l'erreur en cours. Sans 
elle, l'execution de Basic stoppera a la prochaine erreur ou au prochain 
On Error GoTo etiquette. 

Important 

Dans un traitement d'erreur, l'instruction Resume doit apparaTtre le plus rapidement possible poureviter 
qu'une deuxieme erreur ne se produise avant la fin du traitement. 



II peut etre necessaire d'ignorer volontairement les erreurs d'execution. C'est en par- 
ticulier le cas, suite a une erreur fatale, dans la phase de liberation des ressources 
avant d'arreter le programme. Basic propose pour cela l'instruction : 

| On Error Resume Next 

Cette variante d'instruction On Error ne doit pas etre confondue avec l'instruction 
Resume Next. Elle est en fait equivalente a : 

On Error GoTo etiquettelnvisibl e 

' - - - - autres instructions 
Exit Sub 

et i quettelnvi si bl e : 
Resume Next 

L'exemple suivant declenche volontairement deux erreurs, mais le programme s'ache- 
vera malgre tout sans message d'erreur ainsi que le montrent les instructions Pri nt. 

rem Code06-01 . odt bibli : Erreurs Module3 
Option Explicit 



L' 



instruction Resume est indispensable 



Ignorer les erreurs 



Le langage OOoBasic 

Deuxieme partie 

Sub IgnorerErreursO 
Dim vl As Double 

On Error Resume Next 

MsgBox FileLen("") 1 premiere erreur ignoree 
print "Repere 1" 
vl = 0 

vl = 37/vl 1 deuxieme erreur ignoree 

print "Repere 2" 
On Error GoTo 0 
End Sub 

Evidemment, ce genre de « non-traitement » doit etre reserve a des cas justifies, et 
dans les sequences les plus simples possibles. 



Informations sur I'erreur 

Quelques fonctions Basic peuvent servir a analyser I'erreur survenue : 

• Erl renvoie le numero de la ligne ayant declenche I'erreur. 

• Err renvoie un numero d'erreur. 

• Error renvoie le texte explicatif de I'erreur, dans la langue de la version localisee 
d'OpenOffice.org. 

Liste des numeros d'erreur 

La liste des numeros d'erreur est bien cachee dans l'aide en ligne (F1) pour Basic, a la 
page Debogage de programmes Basic, qui de surcroit est incomplete. Le tableau 6-1 
donne une liste des codes d'erreur avec un diagnostic plus clair. Elle est basee sur le 
resultat d'execution d'une macro du document Code06-01.odt. 



Tableau 6-1 Erreurs d'execution Basic 





1 


Une exception s'est produite : 


2 


Erreur de syntaxe 


3 


Return sans Cosub 


4 


Entree incorrecte. Reessayez. 


5 


Appel de procedure non valide 


6 


Debordement 


7 


Memoire insuffisante 


8 


Matrice deja dimensionnee 
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Tableau 6-1 Erreurs d'execution Basic (suite) 



Numero Diagnostic 


9 


Index hors de la plage definie 


10 


Definition dupliquee 


11 


Division par zero 


12 


Variable non definie 


13 


Types de donnees incoherent 


14 


Parametre non valide 


18 


Processus interrompu par I'utilisateur 


20 


Reprendre sans erreur (instruction Resume employee sans erreur prealable) 


28 


Memoire de la pile insuffisante 


35 


La sous-procedure ou procedure fonctionnelle n'est pas definie 


48 


Erreur lors du chargement d'un fichier DLL 


49 


Convention d'appel DLL incorrecte 


51 


Erreur interne 


52 


Nom ou numero de fichier non valide 


53 


Fichier introuvable 


54 


Mode de fichier incorrect 


55 


Fichier deja ouvert 


57 


Erreur d'E/S de peripherique 


58 


Le fichier existe deja 


59 


Longueur d'enregistrement incorrecte 


61 


Support plein (disquette, disque dur, cle USB, etc) 


62 


La lecture depasse la fin du fichier 


63 


Numero d'enregistrement incorrect 


67 


Fichiers trop nombreux 


68 


Peripherique non disponible 


70 


Acces refuse 


71 


Le support n'est pas pret (disque dur, cle USB, etc.) 


73 


Fonction non implemented 


74 


Impossible de renommer sur des unites differentes 


75 


Erreur d'acces au chemin ou fichier 


76 


Chemin introuvable 


91 


Variable d'objet non definie 


93 


ChaTne de caracteres non valide 


94 


Utilisation du zero interdite 
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Tableau 6-1 Erreurs d'execution Basic (suite) 
Diagnostic 



250 


Erreur DDE 


280 


Attente de reponse dans une connexion DDE 


281 


Aucun canal DDE libre 


282 


Aucune application ne reagit a la tentative de connexion DDE 


283 


Trap d'applications repondent a la tentative de connexion DDE 


284 


Canal DDE verrouille 


285 


L'application externe ne peut pas executer I'operation DDE 


286 


Delai depasse lors de I'attente de la reponse DDE 


287 


L'utilisateur a appuye sur Echap pendant I'operation DDE 


288 


L'application externe est occupee 


289 


Donnees non fournies dans I'operation DDE 


290 


Le format des donnees est incorrect 


291 


L'application externe a ete interrompue 


292 


La connexion DDE a ete interrompue ou modifiee 


293 


Methode DDE appelee sans avoir ouvert un canal DDE 


294 


Format de lien DDE incorrect 


295 


Le message DDE a ete perdu 


296 


Collage du lien deja execute 


297 


Impossible de definir le mode du lien, car le titre du lien n'est pas valide 


298 


Le DDE requiertDDEML.DLL 


323 


Impossible de charger le module a cause d'une erreur de format 


341 


Index d'objet non valide 


366 


L'objet n'est pas disponible (pas de document ou pas de vue active du document) 


380 


Valeur de propriete incorrecte 


382 


Cette propriete est en lecture seule 


394 


Cette propriete est en ecriture seule 


420 


Reference d'objet non valide 


423 


Propriete ou methode introuvable 


424 


Objet requis 


425 


Utilisation incorrecte d'un objet 


430 


Cet objet ne supporte pas I'automatisation OLE 


438 


L'objet ne supporte pas cette propriete ou methode 


440 


Erreur lors de I'automatisation OLE 


445 


L'objet indique ne supporte pas cette action 
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Tableau 6-1 Erreurs d'execution Basic (suite) 



Numero Diagnostic 


446 


L'objet indique ne supporte pas les arguments nommes 


447 


L'objet indique ne supporte pas I'environnement linguistique actuel 


448 


L'argument nomme est introuvable 


449 


L'argument n'est pas facultatif 


450 


Nombre d'arguments incorrect 


451 


L'objet n'est pas une liste 


452 


Nombre ordinal non valide 


453 


La fonction DLL indiquee n'existe pas 


460 


Format de presse-papier incorrect 


951 


Symbole imprevu : xxxx 


952 


Requis : xxxx 


953 


Symbole requis 


954 


Variable requise 


955 


Etiquette requise 


956 


Impossible d'attribuer la valeur 


957 


La variable est deja definie 


958 


La sous-procedure ou procedure fonctionnelle est deja definie 


959 


L'etiquette est deja definie 


960 


Variable introuvable 


961 


Tableau ou procedure introuvable 


962 


Procedure introuvable 


963 


L'etiquette n'est pas definie 


964 


Type de donnees inconnu 


965 


Exi t requis 


966 


Bloc destructions encore ouvert : xxxx manquant 


967 


Erreur de parentheses 


968 


Le symbole a deja recu une autre definition 


969 


Les parametres ne correspondent pas a la procedure 


970 


Le nombre contient un caractere incorrect 


971 


Vous devez dimensionner le tableau 


972 


El se/Endi f sans If 


973 


xxxx interdit dans une procedure 


974 


xxxx interdit en dehors d'une procedure 


975 


Les dimensions indiquees ne concordent pas 
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Tableau 6-1 Erreurs d'execution Basic (suite) 



Numero Diagnostic 


976 


Option inconnue : xxxx 


977 


La constante a ete redefinie 


978 


Le programme est trap volumineux 


979 


Type Stri ng ou tableau interdit 


1000 


L'objet ne possede pas cette propriete 


1001 


L'objet ne possede pas cette methode 


1002 


L'argument requis fait defaut 


1003 


Nombre d'arguments incorrect 


1004 


Erreur dans I'execution d'une methode 


1005 


Impossible de definir la propriete 


1006 


Impossible de determiner la propriete 


65535 


Fehler 65 535: Kein Fehlertext verfuegbar! 

(texte allemand signifiant : Erreur 65535 : pas de message d'erreur disponible !) 



Comprendre les messages d'erreur OOoBasic 

Les messages d'erreur d'execution de OpenOffice.org Basic sont souvent assez peu 
comprehensibles. Void pour vous aider quelques informations sur des messages que 
Ton rencontre frequemment. 

Variable non definie 

Ce message apparait si vous avez utilise l'option de declaration obligatoire des 
variables : 

Option Explicit 

Quelque part sur la ligne en erreur, une variable n'a pas ete declaree prealablement. 
Souvent, il s'agit d'une simple faute de frappe. Relisez encore une fois... et benissez 
l'Option Explicit. 

Variable d'objet non definie 
Premier cas 

Vous utilisez une propriete ou une methode d'une variable objet, mais cette variable 
est un objet vide (Null). Par exemple : 

Dim tata as object, toto as object 
I tata = toto. true 
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L'erreur est que la variable toto n'est pas un veritable objet, puisque nous avons 
oublie de lui affecter un objet API. Basic ne peut pas trouver un true dans cet objet ! 

Prenons un contre-exemple. Ceci fonctionne sans erreur : 

Dim tata as object, toto as object 
tata = toto 

En effet, cela revient a affecter a tata une variable objet de valeur Nul 1 . 

En pratique, ce cas arrive lorsqu'une fonction API se contente de renvoyer un objet 
Null, sans erreur d'execution. Par exemple, la methode loadComponentFromURL ren- 
voie Null si le document existe mais n'a pu etre ouvert car il est protege par un mot 
de passe. On doit alors tester le resultat avec la fonction IsNul 1 . 

Deuxieme cas 

II fallait transmettre un objet API, mais par ignorance ou simple « bourde », vous 
transmettez un autre type (valeur numerique, chaine de caracteres...), comme ici sur 
la derniere ligne : 

Dim monDocument As Object, nomlmpr As String 
nomlmpr = "<Marketi ng>" 
monDocument = Thi sComponent 
monDocument . Pri nter = nomlmpr 

Si vous n'utilisez pas Option Explicit, l'erreur peut aussi etre une faute de frappe 
dans le nom d'une variable passee en argument a la fonction API : ce nom est alors 
interprete comme une nouvelle variable de type Variant. Si vous aviez utilise 
l'option, le message d'erreur aurait ete plus clair. 

Troisieme cas 

Le message apparait sur la ligne de declaration d'une Sub ou Function lorsqu'elle est 
appelee, dans certains cas. Prenons un exemple : 

Sub demoBogue 

Dim doc As Variant, adr As String 
doc = Thi sComponent 
traitement (doc, 1)' fonctionne 

adr = ConvertToURL("C:\Docs OpenOf f i ce\toto . odt") 
traitement (adr , 0)' declenche une erreur sur la routine 
End Sub 

Sub traitement(a As Variant, d As Long) 

if d=0 then 

MsgBox("Sauvez le document!") 
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el se 

MsgBox("Adresse du fichier : " & a. URL) 
end "if 
End Sub 

En principe, evitez d'utiliser un meme argument pour transmettre des donnees tres 
differentes. Mais cette construction est parfaitement correcte, et il existe des cas 
complexes ou elle est bien utile. Malheureusement, vous etes victime de 
Tissue 70616, Basic n'accepte pas qu'un argument recoive une valeur non objet si cet 
argument est employe comme un objet dans la routine. Pour contourner ce bogue, il 
suffit d'utiliser une variable intermediate. Pensez a ajouter un commentaire pour le 
lecteur du code ! 

Sub traitement(al As Variant, d As Long) 
Dim a As Variant 

a = al' contournement du bogue Issue 70616 
if d=0 then 

MsgBox("Sauvez le document!") 
el se 

MsgBox("Adresse du fichier : " & a. URL) 
end if 
End Sub 

Utilisation incorrecte d'un objet 

Cela signifie que vous essayez d'affecter a une variable objet quelque chose qui nest 
pas un objet, par exemple une valeur numerique, ou une chaine de caracteres, comme 
ici 1' element Author, qui est une chaine de caracteres : 

I Dim tata As Object 
tata = ThisComponent.DocumentProperties. Author 

Valeur de propriete incorrecte 

Une instruction ou une variable attend une valeur numerique ou Stri ng, et vous lui 
transmettez un objet. 

Vous devriez probablement utiliser une propriete de cet objet, ou vous vous etes 
trompe de propriete, ou la propriete de l'objet ne renvoie pas ce que vous supposez. 
Dans cet exemple, CreationDate renvoie une structure UNO et non un Stri ng. 

Dim s As String 

s = ThisComponent.DocumentProperties. CreationDate 
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Propriete ou methode introuvable 

Ce message est assez explicite : vous cherchez a utiliser dans un objet (qui existe 
bien) une propriete ou une methode que 1' objet ne possede pas. Souvent c'est une 
faute typographique, parfois c'est une mauvaise connaissance de l'API comme ici, 
pour un document Writer : 

Dim tata As Object 

tata = thisComponent.DrawPages 

La propriete est DrawPage, sans s, alors qu'un document Draw possede effectivement 
une propriete DrawPages ! Ne cherchez pas a deviner une propriete d'un objet API, 
vous perdrez votre temps. Relisez plutot ce livre, et utilisez l'outil Xray. 

Sous-procedure ou procedure de fonction non definie 

Dans l'instruction en faute, Basic pense que vous essayez d'appeler une fonction ou 
une procedure qu'il ne connait pas. Verifiez l'orthographe de la procedure que vous 
voulez utiliser, et verifiez quelle existe bien. Exemple : 

sleep(lOOO) 

L'instruction ci-dessus donne cette erreur, car elle n' existe pas en Basic (mais elle 
existe dans d'autres langages). L'equivalent Basic est : 

wait (1000) 

Une exception s'est produite 

Le terme anglais exception signifie « anomalie logicielle ». Sur un appel de fonction 
API, vous avez declenche un message d'erreur accompagne d'informations comme : 

I Type: com . sun . star . uno . RuntimeException 
Message : (texte en anglais). 

Parfois la section Type indique un nom d'exception plus specifique. Bien souvent la 
section Message ne contient rien. C'est la fonction API qui vous renvoie un dia- 
gnostic suite a ses propres controles. Verifiez chacun des arguments et relisez le livre 
ou la documentation de l'API. 

La raison est parfois plus subtile : 

Dim MonDocument As Object, MonTexte As Object 
Dim MonCurseur As Object, MonCadre As Object 

MonDocument = Thi sComponent 
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MonTexte = MonDocument.Text 
MonCurseur= MonTexte . createTextCursor 

MonCadre = MonDocument . createInstance("com . sun . star . text .Text Frame") 
MonCad re. Width = 10400 ' 104 mm largeur 
MonCadre. Height = 2530 ' 25,3 mm de haut 
MonCadre. String = "hello" 

Ici, il s'agit d'une erreur de methodologie : l'API ne permet pas d'initialiser la pro- 
priete Stri ng du cadre avant de l'avoir insere dans le texte. 

Cannot coerce argument type during corereflection call! 

Ce message en anglais est issu de l'API. II nest comprehensible que par un informa- 
ticien connaissant les mecanismes internes de OOoBasic. En termes courants il 
signifie : vous m'avez transmis un argument dont le type n'est pas compatible avec 
celui que j'attends, je ne sais pas i'utiliser. 

En pratique, un des arguments servant a appeler la methode API est incorrect. A 
vous de trouver de quel argument il s'agit, et en quoi il est incorrect. Relisez la docu- 
mentation de l'API ou le chapitre correspondant dans ce livre. Void un exemple 
assez theorique : 

Dim monDocument As Object, monTexte As Object, monCurseur As Object 
monDocument = Thi sComponent 
monTexte = Thi sComponent. Text 

monCurseur = monTexte. createTextCursorByRange(monDocument) 

L'argument de createTextCursorByRange n'est pas une zone de texte. Ce message, 
heureusement, est progressivement remplace dans l'API par un diagnostic plus clair. 



Portee d'un traitement d'erreur 

Un traitement d'erreur en vigueur dans un sous-programme A sera utilise par toute 
erreur declenchee dans un sous-programme B appele directement ou indirectement 
depuis le sous-programme A. 

Dans cet exemple, nous allons declencher et traiter une erreur dans le sous-pro- 
gramme Etagel, puis dans le sous-programme Etage2, lui-meme appele par Etagel. 
Les nombreux pri nt reperent l'avancement de 1' execution. 

rem Code06-01.odt bibli : Erreurs Module4 
Option Explicit 
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Sub PorteeTraitementErreurs 

On Error goto TraiterErreur 

print "Premier appel Etagel" 

Etagel(O) ' appel d'un sous-programme 

print "Deuxieme appel Etagel" 

Etagel(lOOO) 

print "Fin du programme principal" 
Exit Sub 

TraiterErreur: 

print "Erreur " & erl , error 

Resume Next 
End Sub 



Sub Etagel(vl As Long) 
Dim v2 As Long 

print "Etage 1, argument " & vl 
v2 = 1/vl 

print "Appel Etage2" 

Etage2(vl) ' appel d'un sous-programme 
End Sub 



Sub Etage2(v6 As Integer) 

Dim v7 As Integer 

print "Etage 2, argument " & v6 

v7 = v6 * v6 

End Sub 

A l'inverse, si un traitement d'erreur est mis en place dans un sous-programme 
appele, il est desactive au retour du sous-programme. 

rem Code06-01 . odt bibli : Erreurs Module5 
Option Explicit 

Sub ErreurNonTraiteeO 
Dim v3 As Integer 

CererErreur ' appel d'un sous-programme 
v3 = 1000 

v3 = 1000*v3 ' declenche une erreur 
End Sub 



Sub GererErreurO 
On Error goto TraiterErreur 
print "Cestion d'erreur en place" 
Exit Sub 
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Trai terErreur : 

print "Erreur " & erl , error 

Resume Next 
End Sub 



Le traitement d'erreur pour simplifier le codage 

Dans certains cas, le traitement d'erreur peut s'averer un moyen simple pour capturer 
differents cas anormaux qui meritent le meme traitement. Plusieurs des routines de 
l'annexe B emploient justement cette methode. 

Declencher une erreur 

Dans le meme esprit de simplification, il peut etre interessant de declencher une 
erreur identique a un des codes d'erreur repertories dans le tableau 6-1. Par exemple, 
pour declencher l'erreur 70, il suffit d'executer l'instruction suivante : 

err = 70 

Ce mecanisme a ete utilise pour lister tous les codes d'erreur (voir le document 
Code06-01.odt dans le Zip telechargeable). Nous ne detaillerons pas la macro car 
elle necessite des connaissances sur l'ecriture dans Writer que nous verrons au 
chapitre 8. 



Conclusion 

La gestion des erreurs peut etre considered comme un travail ingrat mais se revele 
absolument indispensable a la construction d'un programme robuste dans lequel 
l'utilisateur peut avoir confiance. Nous nous sommes attaches a presenter les 
methodes permettant d'utiliser les fonctionnalites offertes par OOoBasic. 

Ce chapitre clot notre description de OOoBasic. Rappelons que l'aide (F1) est facile- 
ment accessible : n'hesitez pas a la consulter pour verifier la syntaxe des instructions. En 
effet, si vous connaissez d'autres langages, votre memoire peut vous induire en erreur. 

Fort de cette connaissance de OOoBasic, la partie suivante va nous plonger dans la 
manipulation des documents OpenOffice.org au travers de l'API. 
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Manipu 
les documents 
OpenOffice.org 

Vous allez maintenant apprendre a ecrire ou modifier des documents 
OpenOffice.org : Writer, Calc, Draw, Impress. Vous aurez besoin d'utiliser l'API, 
qui constitue le cceur de la programmation OpenOffice.org dans quelque langage 
que ce soit. Mais nous eviterons les exposes theoriques rebarbatifs pour nous con- 
centrer sur les solutions a des besoins reels. 



OpenOffice.org reutilise des concepts generaux dans chaque type de document, 
mais avec des variations propres a chacun. Nous avons regroupe les principes com- 
muns dans le chapitre « Les documents OpenOffice.org » et les aspects specifiques 
dans les chapitres suivants. II subsiste cependant des redondances, justifiees par des 
differences parfois subtiles ou par souci de faciliter la lecture. Les chapitres consa- 
cres aux documents Writer, Calc et Draw/Impress sont assez independants, bien 
que nous renvoyions parfois a un autre chapitre (souvent celui consacre au module 
de traitement de texte Writer) ou tel concept a ete detaille. Dans chacun de ces cha- 
pitres, il n'est nul besoin d'effectuer une lecture complete : apres avoir acquis les 
notions de base, utilisez ensuite le livre comme une reference, et n'approfondissez 
que les sujets qui vous sont utiles. 
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Dans ce chapitre, nous allons decrire des aspects communs a tous les documents 
OpenOffice.org : comment charger un document, le sauvegarder, l'imprimer sont 
des notions fondamentales a connaitre. Le reste du chapitre aborde d'autres elements 
communs aux differents types de documents ; il n'est pas necessaire de les etudier a la 
suite, reprenez ce chapitre en fonction de vos besoins. 



Ce qu'il faut savoir sur l'API 

A partir de ce chapitre, nous allons employer une partie des ressources de l'API Open- 
Office.org afin de manipuler des documents par programmation. Le sigle API est 
l'acronyme de l'anglais Application Programming Interface (Interface de programmation 
de l'application). Pour utiliser correctement l'API, on doit connaitre quelques concepts 
que nous n'avons pas vus jusqu'ici. En voici une description tres succincte. 
• Les structures de donnees UNO sont des objets qui regroupent plusieurs don- 
nees. Chaque donnee possede un nom ; on accede a une de ces donnees en ajou- 
tant un point et le nom de celle-ci a droite du nom de la variable contenant la 
structure. Chaque donnee contient une valeur d'un type precise dans la documen- 
tation. Cela peut etre un type simple (entier, chaine, etc.), un tableau, un objet, ou 
meme une autre structure UNO. L'API definit un grand nombre de structures 



Manipuler les documents OpenOffice.org 

Troisieme partie 



UNO, chacune ayant ses caracteristiques. Avec OOoBasic nous emploierons le 
type Object pour une variable destinee a contenir une structure UNO. Notez 
cependant que le type Vari ant est aussi valable. 

• Les objets UNO sont des concepts logiciels qui « savent faire certaines choses ». 
Prenons une analogie : un objet du type Chien. Un chien sait aboyer, mordre, 
rapporter la balle : ce sont des methodes de l'objet Chien ; rapporter la balle est 
une methode qui est une fonction, car elle nous donne un resultat, la balle. Un 
chien possede des caracteristiques : son poids, son pelage, son collier : ce sont des 
proprietes de l'objet Chien. Nous pouvons nous occuper de plusieurs chiens, cha- 
cun pourra aboyer ou mordre selon l'occasion, chacun aura un poids, un pelage 
particuliers. De meme, plusieurs objets du meme type auront les memes metho- 
des et proprietes, mais elles s'appliqueront a l'objet qui nous interesse. Avec 
OOoBasic nous emploierons aussi le type Object (ou le type Variant) pour une 
variable destinee a contenir un objet. 

• Les methodes d'un objet sont des sous-programmes ou fonctions utilisables seu- 
lement avec l'objet. On utilise une methode en ajoutant un point et le nom de 
celle-ci a droite du nom de la variable objet. Une fonction d'un objet renvoie un 
resultat de type simple ou complexe. 

• Les proprietes d'un objet sont similaires a des variables de donnees, mais seule- 
ment utilisables avec l'objet ; on utilise une propriete en ajoutant un point et le 
nom de celle-ci a droite du nom de la variable objet. Chaque propriete contient 
une donnee de type simple ou complexe. En general, une propriete peut etre lue 
et ecrite, mais parfois seulement lue ou seulement ecrite. 

• Les pseudo-proprietes sont une facilite d'OOoBasic et quelques autres langages. 
Les objets comportent souvent une methode simple pour ecrire 
(setXxx(argument)) ou une fonction sans argument pour lire (getXxxO) une 
donnee interne; par exemple, une methode setPrinter et une fonction 
getPrinter. OOoBasic simplifie l'ecriture en assimilant les deux a une propriete 
Printer. Nous ne distinguerons en general pas les pseudo-proprietes des vraies 
proprietes. 

• Les attributs d'un objet sont, pour OOoBasic et d'autres langages de script, utili- 
ses comme des proprietes. 

• Avec OOoBasic il n'est pas necessaire de respecter la casse (majuscules, minuscu- 
les) des noms de methodes et de proprietes. Cependant nous vous conseillons de 
la respecter : ceci facilite la relecture des noms compliques, car ils sont composes 
de mots anglais resumant la signification de la methode ou propriete. 

Lannexe A donne plus d'informations sur l'API OpenOffice.org et sa documenta- 
tion, telechargeable ou consultable sur Internet. Des explications techniques, en 
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Pour les experts Programmation objet 

L'API est orientee objet, mais OpenOffice.org Basic n'est pas un langage de programmation oriente objet. 

anglais et reservees aux programmeurs experimentes, se trouvent dans le Developer's 
Guide, disponible a cette adresse : 

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ 
OpenOffice.org_Developers_Guide 

Nous ferons occasionnellement reference a certains chapitres du Developer's Guide, 
pour ceux desireux d'approfondir. 

A RETENIR Noms des variables des exemples 

Pour nos exemples de macros, nous utiliserons systematiquement pour les variables importantes des 
noms significatifs en francais. Nous reprendrons les memes noms d'un exemple a I'autre, ce qui vous 
aidera a comprendre. Pour nous, cela reduit I'effort de codage grace a la plus belle invention de 
I'informatique : le copier-coller. 



Acceder au document 

Pour qu'une macro puisse manipuler un document OpenOffice.org, il est necessaire 
de le referencer a travers une variable de type Object. Trois situations sont possibles : 

• le document est celui a partir duquel nous avons lance la macro ; 

• il s'agit d'un autre document qui, par exemple, n'est pas encore ouvert ; 

• nous voulons creer un nouveau document. 

Chaque cas necessite une methode particuliere, que nous allons expliquer. Une fois 
l'objet document obtenu, nous pourrons le manipuler (les principes dependent du 
type de document, ce sera l'objet des chapitres suivants). 



A RETENIR monDocument 

Dans la plupart des exemples de I'ouvrage nous initialiserons la variable objet monDocument avec le 
document a partir duquel la macro est lancee. Mais ceci n'a pas d'importance, les exemples fonctionnent 
avec tout autre document reference par la variable monDocument. 
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Acceder au document en cours 

Ceci est le cas le plus courant. La macro est lancee a partir du document qui nous 
interesse, soit par le menu Outils>Macros>Macro..., soit par un bouton d'une barre 
d'outils ou un bouton sur le document, soit par un raccourci clavier, etc. 

Nous allons declarer dans notre macro une variable objet et l'initialiser ainsi : 
1 methode 1 

Dim monDocument As Object 
monDocument = ThisComponent 

Et voila ! Nous avons maintenant une variable qui reference notre document. 

Le terme ThisComponent est une fonction simplificatrice offerte par OOoBasic. II a 
l'avantage de fonctionner meme si la macro est executee dans l'EDI. Si la macro est 
declaree dans « Mes Macros » et executee depuis l'EDI, le document OpenOffice 
obtenu est celui dont la fenetre est juste en-dessous de celle de l'EDI. 

II existe deux autres manieres d'obtenir le document en cours, plus complexes et 
incompatibles avec une execution dans l'EDI. La methode 3 est courante pour les 
langages autres que Basic : 

1 methode 2 

Dim monDocument As Object 

monDocument = StarDesktop.CurrentComponent 

' methode 3, strictement equivalente a la methode 2 
Dim monBureau As Object, monDocument As Object 
monBureau = CreateUnoServi ce("com . sun . star . frame . Desktop") 
monDocument = monBureau .CurrentComponent 

Pour les raisons exposees plus haut, nous n'utiliserons que la premiere methode. 
D'une maniere generale, nous presenterons toujours les codages les plus simples. 



A RETENIR StarDesktop 

Le terme StarDesktop est une autre fonction simplificatrice offerte par OOoBasic, qui renvoie I'objet 
application OpenOffice.org. Comme il est parfaitement possible de lancer une macro sans document 
ouvert, StarDesktop est alors le moyen d'obtenir certaines entites, comme la fenetre courante, ou 
certaines routines. 
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Acceder a un autre document 

Nous utiliserons pour cela l'objet StarDesktop, qui expose la methode 
1 oadComponentFromURL. Cette derniere nous sert a recuperer un document a partir de 
son adresse fichier exprimee sous la forme d'une URL. 

Les utilisateurs Unix sont familiers avec les adresses URL, mais pas les utilisateurs de 
MS-Windows. Void une meme adresse exprimee dans la syntaxe MS-Windows et 
dans la syntaxe URL : 

C:\Docs OpenOffice\eleves.ods ' adresse au format MS-Windows 
file:///C:/Docs%200penOffice/%C3%A91%C3%A8ves.ods ' adresse au format URL 

Cet exemple vous montre que la traduction n'est pas toujours simple. Pour eviter des 
erreurs, il est preferable d'utiliser la fonction ConvertToURL de Basic, qui recoit en 
argument une adresse dans le format du systeme d'exploitation et renvoie l'equivalent 
en syntaxe URL. Les deux adresses sont des chaines de caracteres. La fonction 
ConvertFromURL effectue la conversion inverse. 

Le codage suivant realise le chargement d'un document. Nous l'expliquerons juste 
apres. 

Dim monDocument As Object, adresseDoc As String 
Dim propFichO 

adresseDoc = ConvertToURL("C:\Mes Documents\tata.ods") 

monDocument = StarDesktop. loadComponentFromURL( 

adresseDoc, "_blank", 0, propFichO ) 

Le caractere _ a la fin de l'avant-derniere ligne sert uniquement a indiquer le prolon- 
gement de l'instruction sur la ligne suivante. Nous l'utilisons pour des raisons de 
mise en page, mais dans vos macros vous pouvez mettre toute l'instruction sur la 
meme ligne. 

La methode 1 oadComponentFromURL comporte quatre arguments obligatoires. Les 
arguments employes ici correspondent au cas de loin le plus courant. 

La variable adresseDoc est initialisee avec FURL du document a charger. Elle sera 
transmise en premier argument a la methode 1 oadComponentFromURL de l'objet 
StarDesktop. 

Le deuxieme argument est une chaine de caracteres, que vous devez ecrire exacte- 
ment comme indique. 

Le troisieme argument est generalement la valeur zero. 
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Pour les experts Arguments 2 et 3 

Seuls des cas tres particuliers peuvent necessiter d'autres valeurs pour les arguments 2 et 3 de la 
methode loadComponentFromURL. Les experts trouveront de plus amples informations (en anglais) 
dans le Developer'sGuide, chapitre Office Development>Handling Documents. 



Le quatrieme argument precise certaines options concernant le fichier. La variable 
propFich est un peu particuliere : ici, elle sert seulement a indiquer que le quatrieme 
argument est un tableau vide, c'est-a-dire que nous n'utilisons que les options par 
defaut. Un tableau vide se definit comme indique sur la ligne Di m correspondante : 
avec deux parentheses sans indication de dimension. Le type de la variable nest pas 
important dans ce cas, aussi nous utilisons le type par defaut, Vari ant. Bien que cela 
ne soit pas obligatoire, nous avons ajoute des parentheses vides a propFich pour 
signaler que nous transmettons un tableau. 

A la place du tableau vide propFich () on peut aussi utiliser la fonction Basic Array 
que nous avons vue au chapitre 3. 

monDocument = StarDesktop . 1 oadComponentFromURL(_ 
adresseDoc, "_blank", 0, ArrayO ) 

En effet, employee sans argument cette fonction renvoie aussi un tableau vide. 

Si le document recherche n'existe pas, ou si FURL est incorrecte, la methode 
loadComponentFromURL declenche une erreur (en anglais, exception) avec ce message : 

Type: com.sun.star.lang.IllegalArgumentException Message: URL seems to be an 
unsupported one. 

II est done necessaire, soit d'ajouter un traitement d'erreur, soit de verifier auparavant 
que le fichier existe bien (voir au chapitre 5 la fonction Fi 1 eExi sts () ) 

Si le fichier existe, mais est protege par un mot de passe et que celui-ci n'est pas 
fourni ou incorrect, ou bien si le type de fichier n'est pas reconnu par OOo, la 
variable monDocument recevra la valeur Null . Nous pouvons verifier ceci : 

if IsNull (monDocument) then 

MsgBox("Le chargement du document est impossible", 16) 
end if 

Proprietes d'ouverture de document 

Le quatrieme argument de loadComponentFromURL permet de preciser une ou plu- 
sieurs options de chargement. Afin de pouvoir transmettre un nombre quelconque 
d'options dans ce quatrieme argument, ces options sont groupees dans un tableau. Si 
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une option n'est pas precisee, l'API utilise une valeur par defaut. Chaque option est 
transmise sous la forme d'une structure, tres courante dans l'API, appelee valeur de 
propriete (en anglais, PropertyVal ue) decrite au tableau 7-1. 

Tableau 7-1 Structure PropertyValue 



Name 


String 


Le nom de la propriete. Respecter les majuscules et minuscules de ce nom. 


Value 


Variant 


Valeur de la propriete. Le type exact (String, Long, Double, 
Bool ean, objet API...) depend de la propriete, il est important de respec- 
ter le type attendu. 


Handle 


Long 


Donnee sans utilite pratique. Ne pas utiliser. 


State 


Object 


Donnee sans utilite pratique. Ne pas utiliser. 



Pour transmettre les options, nous devons declarer un tableau dont chaque element 
est une structure PropertyValue decrivant l'option. L'ordre des options est sans 
importance. Le premier element du tableau a pour index zero. Par exemple, la ligne 
ci-dessous declare un tableau de deux structures, un element d'index 0 et un element 
d'index 1 : 

| Dim propFich(l) As New com. sun. star. beans. PropertyValue 

Pour transmettre une seule option nous devons quand meme utiliser un tableau, qui 
aura alors un seul element, d'index 0 : 

| Dim propFich(O) As New com. sun. star. beans. PropertyValue 

Cette declaration Dim utilise la forme As New qui precise que le type demande est 
indique par la sequence qui suit. Cette sequence doit etre ecrite exactement, en res- 
pectant la casse (majuscules, minuscules). Chaque structure particuliere utilisee par 
l'API possede une sequence specifique, commencant toujours par com. sun . star. 

En reprenant 1' exemple precedent, nous allons supposer que le document est protege 
par un mot de passe. Le mot de passe obtenu de l'utilisateur est transmis par l'option 
Password. La valeur du mot de passe est une chaine de caracteres. Le document sera 
charge de maniere invisible, grace a l'option Hidden. 

Dim monDocument As Object, adresseDoc As String 

Dim propFich(l) As New com. sun. star. beans. PropertyValue 



adresseDoc = convertToURL("C:\Docs OpenOff i ce\tata . ods") 
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propFich(O) . Name = "Password" 

propFich(O) .Value = "lulie37" ' le mot de passe 
propFichCD.Name = "Hidden" 

propFich(l) .Value = True ' charger en invisible 
monDocument = StarDesktop . LoadComponentFromURL(_ 
AdresseDoc, " blank", 0, propFichO) 

Cet exemple vous montre comment remplir un element d'une structure 
PropertyVal ue. Remarquez enfin que le quatrieme argument de 
LoadComponentFromURL utilise des parentheses vides pour signifier a Basic que 
l'ensemble du tableau doit etre transmis. 



Explication Pourquoi faire complique ? 

Vous vous demandez sans doute pourquoi on a choisi de transmettre les options dans un tableau de 
structures ! La raison est que cela permet de transmettre a la methode un nombre variable de parame- 
tres, sans changer la definition de la methode. Les regies de I'API, contrairement a Basic ou d'autres Ian- 
gages, imposent un nombre fixe de parametres pour une methode donnee. Eventuellement un parametre 
pourra prendre une valeur Null, mais il sera toujours present. 

Dans notre cas, I'utilisation de la methode 1 oadComponentFromURL peut employer zero, un ou plu- 
sieurs options. Mais allons plus loin : peut-etre dans le futur les developpeurs souhaiteront introduire une 
nouvelle option. Cela ne posera aucun probleme de compatibility avec les codages existants, car ils n'uti- 
liseront pas cette option, et I'API utilisera une valeur par defaut. Inversement, un nouveau codage utili- 
sant la nouvelle option pourra s'executer sur une version ancienne d'OpenOffice.org : dans ce cas I'API 
ignorera simplement une propriete qu'il ne connait pas, et fonctionnera comme avant. 
Le revers de la medaille est que vous devez bien verifier le nom de chaque propriete transmise dans le 
tableau, un nom incorrect sera ignore sans aucun message d'erreur. 



Le service com. sun. star. document. MediaDescriptor expose les proprietes d'ouver- 
ture et de sauvegarde du document. Les plus utilisees pour l'ouverture d'un document 
sont listees au tableau 7-2. Certaines necessitent des explications complementaires. 

Tableau 7-2 Options pour l'ouverture d'un document 



Hidden 


Boolean 


True pour charger le document de maniere invisible ; valeur 
False par defaut. 


Password 


Stri ng 


Mot de passe (en clair) pour charger un document 
OpenOffice.org protege. 


Readonly 


Boolean 


True pour ouvrir le document en lecture seule ; valeur Fal se 
par defaut. 


Version 


Integer 


Numero de la version a charger (utilisation du systeme de ver- 
sions) 
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Tableau 7-2 Options pour I'ouverture d'un document (suite) 



MacroExecuti onMode 


Integer 


Precise les conditions d'execution des macros du document ; 
constante nommee, voir le tableau 7-3. 


UpdateDocMode 


Integer 


Precise les conditions de mise a jour des liens exernes du 
document ; constante nommee, voir le tableau 7-4. 


Inte racti onHandler 


Ob j ect 


Fonction de dialogue interactif, voir dans le texte : Option 
Password. 


AsTemplate 


Boolean 


Utilisation d'un modele de document. 


Fi 1 terName 


String 


Norn du filtre d'importation ou d'exportation. 


Filter Data 


String 


Options du filtre d'importation ou d'exportation, pour les filtres 
recents. 


FilterOptions 


String 


Options du filtre d'importation ou d'exportation, pour les anciens 
filtres. 



Option Readonly 

L'option Readonly ne vous empeche pas de modifier le document par programmation, 
mais vous ne pourrez pas sauver les modifications par une simple sauvegarde. L'utilisa- 
teur par contre ne peut le modifier qu'apres avoir clique le bouton Edition de fichier. 

Option Password 

Dans l'exemple donne plus haut, nous avions fourni en clair le mot de passe dans 
l'option Password. Ceci est evidemment a eviter. 

L'API OpenOffice.org offre le service InteractionHandler, qui ouvre une boite de 
dialogue standardisee lorsqu'il est necessaire de demander une information a l'utilisa- 
teur. Nous allons l'employer pour lui demander le mot de passe. 

Dim monDocument As Object, adresseDoc As String, demander As Object 
Dim propFich(O) As New com . sun . star . beans . PropertyVal ue 

adresseDoc = convertToURL("C:\Docs OpenOffice\tata.ods") 

' utiliser le dialogue pour demander le mot de passe 

demander = CreateUnoServi ce("com . sun . star . task . Interact ionHandl er") 

propFich(O) .Name = "InteractionHandler" 

propFich(O) .Value = demander 

monDocument = StarDesktop . LoadComponentFromURL(_ 
AdresseDoc, "_blank", 0, propFichQ) 



La fonction Basic CreateUnoServi ce renvoie un objet permettant d'utiliser le service 
InteractionHandler. Ensuite, au lieu d'utiliser l'option Password, on transmet cet objet 
dans l'option Interacti onHandl er. Respectez la casse dans le nom complet du service. 
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OpenOffice, constatant que le document a charger est protege par un mot de passe, 
declenche la boite de dialogue de demande de mot de passe ; si l'utilisateur repond avec 
un mot de passe incorrect, un message d'erreur sera affiche par OpenOffice.org et la 
variable monDocument recevra la valeur Null ; si l'utilisateur annule le dialogue, il n'y 
aura pas de message d'erreur et la variable monDocument recevra aussi la valeur Nul 1 . 

Option MacroExecutionMode 

L'option MacroExecutionMode est indispensable si vous voulez charger un document 
dont vous voulez que les macros puissent etre executees. Le menu Outils> 
Options>OpenOffice.org>Securite precise les conditions habituelles d'execution des 
macros (voir le chapitre 1). L'option MacroExecutionMode permet de tenir eventuel- 
lement compte de cette configuration ou de les ignorer. Les valeurs possibles de 
MacroExecutionMode sont des constantes listees au tableau 7-3. 

Un cas typique est le chargement d'un document dont on sait qu'il contient une 
macro a executer au chargement. Alors on autorisera 1' execution de macros sur ce 
document, quel que soit le niveau de securite, en utilisant la constante : 

com . sun . star . document . MacroExecMode.A LWA YS_EX ECUT E_NO_WA RN 

Les autres constantes s'ecrivent de maniere similaire. Attention a la casse ! Les cons- 
tantes nominees doivent etre ecrites en respectant les majuscules et minuscules, sinon 
elles ne seront pas reconnues. 

Tableau 7-3 Constantes de MacroExecutionMode 



Constante 




NEVER_EXECUTE 


Ne pas executer les macros. Valeur par defaut. 


FROM_LIST 


Executer les macros provenant d'un repertoire de fichiers de 
confiance. 

En dehors des repertoires de confiance, une confirmation 
sera demandee. 


ALWAYS_EXECUTE 


Les macros dont le certificat est reconnu, ou provenant d'un 
repertoire de confiance, sont executees sans avertissement ; 
une confirmation est demandee si les macros ne sont pas 
dans un repertoire de confiance, et pas certifies. 


USE_CONFIG 


Utiliser la configuration, ouvrir une fenetre de dialogue si 
une confirmation est necessaire. 


ALWAYS_EXECUTE_NO_WARN 


Executer les macros sans demande de confirmation ni aver- 
tissement. 


use_config_re:ect_confirmation 


Utiliser la configuration, ne pas executer les macros si une 
confirmation serait necessaire. 
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Tableau 7-3 Constantes de MacroExecutionMode (suite) 
Sign 



USE CONFIG APPROVE CONFIRMATION 


Utiliser la configuration, executer les macros comme si la 
confirmation etait acceptee. 


FROM_LIST_NO_WARN 


Seules les macros provenant d'un repertoire de fichiers de 
confiance seront executees. 


FROM_LIST_AND_SIGNED_WARN 


Les macros dont le certificat est reconnu, ou provenant d'un 
repertoire de confiance, sont executees sans avertissement ; 
une confirmation est demandee si les macros ont un certifi- 
cat inconnu ; si les macros ne sont ni dans un repertoire de 
confiance, ni certifies, el les ne sont pas executees. 


FROM_LIST_AND_SICNED_NO_WARN 


Seules les macros dont le certificat est reconnu, ou prove- 
nant d'un repertoire de confiance, sont executees. Aucun 
avertissement n'est signale. 



En pratique le tableau 7-3 est a interpreter en fonction du niveau de securite de votre 
application, de remplacement du document, de sa signature eventuelle, de la certifi- 
cation eventuelle de cette signature. Autant dire que c'est parfois complexe. 

Si vous employez une valeur d'option necessitant un dialogue de confirmation, vous 
devez employer le service InteractionHandler, que nous avons deja utilise pour 
l'option Password. 

Dim monDocument As Object, adresseDoc As String, demander As Object 
Dim propFich(l) As New com. sun. star. beans. PropertyValue 

adresseDoc = convertToURL("C:\Docs OpenOffice\tata.ods") 

' utiliser le dialogue pour demander 1 'autorisation d'executer les macros 

demander = CreateUnoServi ce ("com . sun . star . task . InteractionHandl er") 

propFich(O) .Name = "InteractionHandler" 

propFich(O) .Value = demander 

propfich(l) .Name = "MacroExecutionMode" 

p ropf i ch (1) . Val ue = com . sun . star . document . Mac roExecMode . ALWAYS_EXECUTE 

Option UpdateDocMode 

L'option UpdateDocMode est utilisee si le document charge contient des liens vers 
d'autres documents, ou un lien vers une base de donnees, afin d'ouvrir un document 
a jour. Les valeurs possibles sont listees au tableau 7-4, void un exemple : 



propFich(O) .Name = "UpdateDocMode" 

propFi ch (0) . Val ue = com . sun . star . document . UpdateDocMode . FULL_UPDATE 
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Tableau 7-4 Constantes de UpdateDocMode 



Constante Signification 


NOJJPDATE 


Ne pas mettre a jour le document. 


QUIET_UPDATE 


Ne mettre a jour que si cela ne necessite pas un dialogue avec I'utilisateur. Par 
exemple un lien vers une base de donnee peut necessiter un mot de passe. 


ACCORDING_TO_CONFIG 


Se conformer a la configuration dans le menu Outils>Options>Writer ou 
Calc>General>Actualiser les liens. 


FULL_UPDATE 


Mettre a jour le document meme si cela necessite un dialogue. 



Option Hidden 

Cette option permet de charger le document sans que I'utilisateur ne le voie. Depuis 
la version 2.2 d'OpenOffice.org, on peut par la suite rendre visible un document 
charge en mode invisible. 



Dim monDocument As Object, adresseDoc As String 

Dim propFich(O) As New com . sun . star . beans . PropertyVal ue 

adresseDoc = convertToURL("C:\Docs OpenOffice\tata.ods") 
propFich(O) .Name = "Hidden" 

propFich(O) .Value = True' charger en invisible 
monDocument = StarDesktop . LoadComponentFromURL(_ 
AdresseDoc, "_blank", 0, propFichO) 
MsgBox("Le document va apparaitre") 

monDocument . Cu r rentCont rol 1 er . Frame . Contai nerWi ndow . Vi si bl e = True 

On peut le remettre invisible, avec la valeur False. La pseudo-propriete Visible ne 
peut pas etre lue, car il hexiste que la methode setVi si ble(). 

Option AsTemplate 

Cette option depend du document charge : document ordinaire, ou document modele. 

Les documents « modeles » (en anglais, template) ont une extension speciale, ott 
pour un modele Writer, ots pour un modele Calc, etc. Sans option particuliere, 
charger un tel document revient a creer un nouveau document sur ce modele. 

Pour modifier un document modele, on doit utiliser l'option AsTempl ate. Cette option, 
de type Bool ean, doit prendre la valeur Fal se afin de charger effectivement le modele. 

Pour un document ordinaire, si on utilise l'option AsTempl ate avec la valeur boo- 
leenne True, ce document sera pris comme modele pour creer un nouveau document. 
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Options de filtre 

Les options FilterName, FilterData, Fi "IterOptions servent pour rimportation (et 
l'exportation) de documents sous un autre format. Voyez la section correspondante 
dans ce chapitre. 

Creer un nouveau document 

Pour creer un nouveau document OpenOffice.org, on utilise la meme methode que 
pour charger un document existant. Cependant, ici, l'adresse du document est une 
convention pour indiquer le type de document a creer. Par exemple, pour un docu- 
ment Calc, nous utiliserons : 

adresseDoc = "private: factory/scale" 

monDocument = StarDesktop . 1 oadComponentFromURL(_ 
adresseDoc, "_blank", 0, propFichO ) 

Le tableau 7-5 liste les differentes pseudo-adresses possibles. L'adresse doit etre 
reproduite exactement dans votre instruction. Le nouveau document obtenu suit le 
modele par defaut en vigueur pour votre configuration d'OpenOffice.org. 



Tableau 7-5 Pseudo-adresses pour creer un document 



Type de document 


Pseudo-adresse 


Texte Writer 


pri vate : facto ry/swri ter 


Document texte MaTtre 


pri vate : facto ry/swri ter/Gl obal Document 


Document HTML 


pri vate : facto ry/swri ter/web 


Tableur Calc 


private : factory/seal c 


Dessin Draw 


pri vate : f actory/sdraw 


Presentation Impress 


private : factory/simpress 


Editeur de formules Math 


pri vate : f actory/smath 



Creer un nouveau document selon modele 

Creer un document qui soit la copie d'un document servant de modele est une 
methode qui peut simplifier considerablement vos macros. En effet, vous pouvez 
creer manuellement le document modele de facon a ce qu'il comporte tous les styles 
de page, de paragraphe, de caractere, des en-tetes et bas de page, des pages en por- 
trait et des pages en paysage, des images integrees, des sections, des tableaux, un 
texte initial et des points de reperage realises avec des signets. Ensuite, vous n'aurez 
plus qua completer le document avec votre macro au lieu de tout creer ex nihilo. Ce 
principe est aussi valable pour un document Calc, Draw, ou autre. 
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Le chapitre 14 vous indique comment retrouver le ou les repertoires des modeles 
dans votre installation OpenOffice.org. 

II existe deux methodes pour creer un nouveau document a partir d'un modele. La 
plus simple est de partir d'un vrai document modele, c'est-a-dire avec une extension 
ott pour Writer, ots pour Calc, etc. II suffit de faire comme si on chargeait le docu- 
ment modele : 

adresseDoc = convertToURL("C:\Mes model es\Doc2col onnes . ott") 

Ce document ne sera pas charge, mais un nouveau document ordinaire sera cree, 
dont le contenu sera identique. Dans l'exemple, nous obtiendrons un nouveau docu- 
ment Writer. 

La deuxieme methode consiste a prendre comme modele un document ordinaire. Le 
document sera charge avec la methode deja vue, mais en utilisant l'option 
AsTempl ate avec la valeur booleenne True. 

Afficher le document en plein ecran 

Une fois le document charge et visible, on peut mettre sa fenetre en plein ecran avec 
une commande . uno: Fullscreen envoyee par le Dispatcher. Le chapitre 14 vous 
montrera comment employer le Dispatcher de maniere tres simple. 



Sauvegarde des modifications 

L'etat actuel du document 

Si votre document a ete modifie, par macro ou par l'utilisateur, il est necessaire de le 
sauvegarder avant de le fermer. La methode i sModi f i ed de l'objet document renvoie 
une valeur de type Bool ean. Elle vaut True si le document a ete modifie. 

"if monDocument . isModified then 

' mettre ici les instructions pour sauver le document 
end if 

L'etat Modifie peut etre change par programme, en utilisant la methode 
setModi f i ed du document, par exemple pour forcer l'apparition du dialogue de sau- 
vegarde si l'utilisateur ferme le fichier : 

monDocument . setModi f ied(True) 
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Le document expose la propriete hasLocation, de type Boolean, qui vaut True s'il 
possede une adresse, ou Fal se si le document est nouveau, pas encore sauvegarde. La 
propriete Locati on, de type Stri ng, vous indique l'URL du fichier original. 

if monDocument . hasLocation then 

adresseDoc = monDocument . Location 
el se 

adresseDoc = convertToURL("C:\Mes Documents\toto . ods") 
end if 



Sauver le document 

Si le document nest pas nouveau, la sauvegarde se fait tres simplement grace a la 
methode store de l'objet document : 

monDocument . store 

Si vous avez cree un nouveau document jamais encore sauve, vous devez preciser le 
nom et 1' adresse du fichier a creer, avec une URL. La methode storeAsURL de l'objet 
document effectue alors la sauvegarde. Elle est l'equivalent de la commande de menu 
Fichier>Enregistrer sous... En reprenant les memes variables que dans les exemples pre- 
cedents, on ecrira dans le cas le plus simple : 

Dim propFich2() 

adresseDoc = convertToURL("C:\Docs OpenOff i ce\toto . ods") 
monDocument. storeAsURL(adresseDoc, propFich2() ) 

Si le repertoire indique n'existe pas, il sera cree automatiquement. 

Ici aussi, nous avons la possibilite d'utiliser des options de sauvegarde. Notre exemple 
n'utilise aucune option particuliere. Les options principales utiles dans une operation 
de sauvegarde sont listees au tableau 7-6. Le principe d'initialisation des options est 
identique a ce que nous avons vu pour les options de chargement d'un fichier. 

Notez que si vous utilisez l'option Password, toute valeur de mot de passe est utili- 
sable, y compris une chaine de caracteres de longueur nulle. Pour demander a l'utili- 
sateur quel mot de passe il souhaite utiliser, creez une boite de dialogue avec une 
zone de texte a remplir, comme explique au chapitre 11. 
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Tableau 7-6 Options de sauvegarde d'un document 





Overwri te 


Bool ean 


True pour ecraser un document deja existant (valeur par defaut) 

Fal se pour ne pas ecraser le document (une erreur sera declenchee en 

cas de tentative de sauvegarde). 


Password 


Stri ng 


Mot de passe pour chiffrer le document. 


Author 


Stri ng 


Auteur de la version du document (utilisation du systeme de versions). 


Version 


Integer 


Numero de version a sauvegarder (utilisation du systeme de versions). 


Comment 


Stri ng 


Commentaire sur la version (utilisation du systeme de versions). 


Fi 1 terName 


Stri ng 


Norn du filtre d'exportation ; voir la section sur les filtres d'import/export. 


FilterData 


Variant 


Options du filtre d'importation ou d'exportation, pour les filtres recents. 


FilterOptions 


Stri ng 


Options du filtre d'importation ou d'exportation, pour les anciens filtres. 



Enregistrer une copie 

Si vous avez ouvert un fichier tata . ods et l'avez sauvegarde par la methode storeAsURL 
sous le nom toto . ods, vous travaillez maintenant dans le document toto . ods. 

En revanche, la methode storeToURL realise une copie du document en cours, et seu- 
lement cela. Ainsi, travaillant sur tata. ods, vous faites une copie appelee 
tataOOl.ods et continuez sur tata. ods. Ceci est utile pour des sauvegardes regu- 
lieres, ou pour faire une copie dans un autre format. 

La methode storeToURL utilise la meme syntaxe que storeAsURL. 

Recharger le document 

La commande de menu Fichier>Recharger consiste a remettre le document dans l'etat 
oil il a ete sauvegarde, en annulant les modifications intervenues. Cette fonctionna- 
lite n'existe pas dans l'API, nous utilisons le Dispatcher ; mais pour eviter l'affichage 
d'un message de confirmation on doit lui faire croire que rien n'a ete modifie : 

dim monDocument as object 
monDocument = thi sComponent 

monDocument . setModi f ied(Fal se) 

Di spatchSimple ("Reload") 

La routine DispatchSimple est un sous-programme utilitaire que nous decrivons au 
chapitre 14. 
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Fermer le document 

La methode recommandee pour fermer un document (ou une fenetre) est la 
suivante : 

on Error Resume Next ' ignorer 1'erreur eventuelle 
monDocument . cl ose(True) 

On Error GoTo 0 ' reprendre le traitement d'erreur normal 

La methode close signale a d'autres programmes utilisateurs que ce document va 
etre ferme. Un de ces programmes peut manifester son mecontentement en declen- 
chant une erreur, que nous ignorerons. Largument True dans la methode close 
signale a ces autres programmes que, s'ils souhaitent continuer quand meme, ils doi- 
vent en assumer la responsabilite (en ce qui concerne la liberation des ressources). 
Vous pourrez lire dans le Developer's Guide, chapitre Office Development>Handling 
Documents> Closing Documents, une discussion tres technique sur ce sujet. 



Exemples recapitulatifs 

Nous allons presenter maintenant des exemples complets de macros qui utilisent les 
notions decrites jusqu'ici dans ce chapitre. Ces macros sont disponibles dans le Zip 
telechargeable. 

Dans le premier exemple, nous executons une macro sur le document en cours. Dans 
ce cas particulier, la macro est incluse dans le document lui-meme. 

rem Code07-04 . odt bibli : LeDocument Modulel 
Option Explicit 

Sub DocumentEnCours () 
Dim monDocument As Object 
monDocument = Thi sComponent 

' afficher tout le texte du document 
MsgBox (monDocument . Text . Stri ng) 

if MsgBox("Fermer ce document ?",4) = 6 then 
' reponse = Oui 

on Error Resume Next ' ignorer 1'erreur eventuelle 
monDocument . cl ose (True) 

On Error GoTo 0 ' reprendre le traitement d'erreur normal 
end if 
End Sub 
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L'instruction permettant d'afEcher le texte du document Writer sera expliquee dans le 
chapitre 8. Nous l'employons simplement pour prouver que nous accedons bien au docu- 
ment. L'instruction MsgBox utilise le parametrage pour afficher un bouton Oui et un 
bouton Non. Relisez eventuellement la description de cette instruction au chapitre 5. 

Dans le deuxieme exemple, nous creons un nouveau document Calc a partir d'une 
autre macro du document Writer. Ce document est modifie, puis sauve a une adresse 
particuliere, en lui mettant un mot de passe. Changez eventuellement cette adresse 
pour etre compatible avec votre systeme. Ce nouveau document est finalement 
ferme. Les explications suivent le codage. 

rem Code07-04 . odt bibli : LeDocument Module2 
Option Explicit 

' modifiez eventuellement cette ligne selon votre systeme 
Public Const leDoc = "C:\Docs OpenOffice\DocHeure.ods" 

Sub CreerDocumentAvecPasseO 
Dim monDocument As Object 
Dim adresseDoc As String 
Dim propFichO 

adresseDoc ="private:factory/scalc" ' nouveau document Calc 
monDocument = StarDesktop . 1 oadComponentFromURL(_ 
adresseDoc, "_blank", 0, propFichO) 
MsgBox "Un nouveau document Calc doit etre affiche maintenant" 

' ecrire l'heure dans la cellule Al de la premiere feuille 
Dim maCellule As Object 

maCellule = monDocument. Sheets(O) .getCellRangeByName("Al") 
maCellule. String = "Ecrit le = " & Date & " Heure " & Time 
MsgBox "Tableur modifie" 

1 convertToURL est inutile avec un systeme Linux 

adresseDoc = convertToURL(l eDoc) 

' sauvegarder le document avec un mot de passe 

Dim propFich2(0) As New com . sun . star . beans . PropertyVal ue 

propFich2(0) .Name = "Password" 

propFich2(0) .Value = "OpenOffice" ' ceci est le mot de passe ! 
monDocument . s to reAslIRL (adresseDoc , propFi ch2 ()) 

MsgBox "Fermeture du document" 
on Error Resume Next 
monDocument . cl ose (True) 
On Error GoTo 0 
End Sub 
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La constante leDoc est declaree Public car nous l'utiliserons aussi dans un autre 
module de la bibliotheque de macros. Apres avoir ouvert un nouveau document 
Calc, nous ecrivons un texte (la date et heure actuelles) dans la cellule Al de la pre- 
miere feuille. Ne vous preoccupez pas de la methode employee, le but est seulement 
de montrer que nous pouvons modifier le document. La variable adresseDoc est ini- 
tialisee avec l'URL de sauvegarde du document. Pour definir l'option « mot de 
passe », nous utilisons une autre variable, car nous avons besoin maintenant d'un 
tableau a un element de structure PropertyVal ue. 



Securite Mot de passe 

Pour simplifier I'exemple, le mot de passe apparaTt en clair dans votre macro. II peut etre judicieux de la 
proteger elle-meme en mettant un mot de passe sur la bibliotheque de la macro, comme vu au 
chapitre 2. Ceci empechera une lecture non autorisee du codage. 



Dans le troisieme exemple, nous allons charger de nouveau le document Calc cree 
precedemment, le modifier puis le refermer. 

rem Code07-04 . odt bibli : LeDocument Module3 
Option Explicit 

Sub ChargerDocumentAvecPasseO 
Dim monDocument As Object 
Dim adresseDoc As String 

Dim propFich(O) As New com . sun . star . beans . PropertyVal ue 

' leDoc est declare dans le module 2 
adresseDoc = convertToURL(l eDoc) 
if not FileExists(adresseDoc) then 

MsgBox("Le document n'existe pas", 16) 

Stop ' arreter l'execution de Basic 
end if 

propFich(O) .Name = "Password" 

propFich(O) .Value = "OpenOffice" ' ceci est le mot de passe ! 
monDocument = StarDesktop . 1 oadComponentFromURL(_ 
AdresseDoc, "_blank", 0, propFichO) 

if IsNull (monDocument) then 

MsgBox("Le document n'est pas chargeable" & chr(13) & _ 
"ou le mot de passe est incorrect", 16) 

Stop ' arreter l'execution de Basic 
end if 

MsgBox "Tableur charge" 
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' ecrire l'heure dans la cellule A2 de la premiere feuille 
Dim maCellule As Object 

maCellule = monDocument . Sheets (0) .getCellRangeByName("A2") 
maCellule. String = "Ecrit le = " & Date & " Heure " & Time 
MsgBox "Tableur modi fie" 

monDocument . store ' sauvegarder (avec le mot de passe) 
on Error Resume Next 

monDocument. close(True) ' fermer le document 
On Error GoTo 0 
End Sub 

Nous reutilisons la variable leDoc du module precedent afin d'obtenir 1'URL du 
document a charger. Pour eviter une erreur d'execution, nous testons d'abord si le 
fichier existe. Ensuite seulement nous chargeons le document. Ici aussi, le mot de 
passe est dans le codage. Nous verifions que le document a bien ete charge en testant 
le contenu de la variable monDocument. Si ce n'est pas le cas, on s'arrete la (l'instruc- 
tion chr(13) sert a changer de ligne dans le message). Dans le cas normal, on ecrit 
un texte dans la cellule A2, on sauvegarde le document et on le ferme. 



Imprimer un document 

Nous decrirons ici les mecanismes d'impression communs a tous les documents. Les 
particularites propres a certains documents sont traitees dans les chapitres qui leur 
sont consacres. Les exemples utilises ici sont disponibles a l'identique dans les 
fichiers du Zip telechargeable : 

• Code07-01.odt pour Writer 

• Code07-02 . ods pour Calc 

• Code07-03 . odg pour Draw 

L'objet Printer 

Tout document dispose normalement d'une imprimante pour son impression. Le 
document expose les caracteristiques de l'imprimante dans l'objet Printer. Ce der- 
nier est un tableau (Array) contenant diverses proprietes listees dans le tableau 7-7, 
qui est suivi de quelques explications complementaires. 
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Tableau 7-7 Proprietes du descripteur d'imprimante 



Name 


Stri ng 


Le nom de la file d'attente de I'imprimante 


PaperOrientation 


Integer 


Orientation du papier ; constante nommee, voir explications. 


PaperFormat 


Integer 


Format du papier ; constante nommee, voir explications. 


PaperSize 


Object 


Taille du papier, largeur et hauteur en twips. 


IsBusy 


Boolean 


True si I'imprimante est occupee (au niveau de la mise en file 
d'attente du travail). 


CanSet PaperOrientation 


Boolean 


True si on peut changer I'orientation du papier. 


CanSet Paper Format 


Boolean 


True si on peut changer le format de papier. 


CanSetPaperSize 


Boolean 


True si on peut imposer une taille quelconque du papier. 



L'orientation du papier ne peut prendre que deux valeurs, sous la forme de constantes 
nominees : 

com . sun . star . vi ew. PaperOri entati on . PORTRAIT 
com . sun . star . vi ew. PaperOri entati on . LANDSCAPE 

Attention a la casse ! Les constantes nominees doivent etre ecrites en respectant les 
majuscules et minuscules. 

Plusieurs formats standardises de papier sont reconnus. Les constantes nominees 
sont de la forme : 

| com . sun . star . vi ew. PaperFormat . A4 

Les differents formats de papier possibles sont : 
| A3 A4 A5 B4 B5 LETTER LEGAL TABLOID USER 

En Europe, nous utilisons essentiellement les formats A3, A4 et A5. Le format USER 
est indique lorsque le format ne correspond a aucun de ceux cites. Dans ce dernier 
cas seulement, la propriete PaperSize est significative ; elle se compose de deux ele- 
ments Width et Height indiquant la largeur et la hauteur en twips. Un twip repre- 
sente l/20 e de point, qui mesure lui-meme l/72 e de pouce. Un pouce correspondant 
a environ 25,4 mm, 1 twip vaut 1,76 centieme de millimetre. 

Cet exemple va lister les proprietes d'imprimante. II est explique juste apres. 



rem Code07-01.odt bibli : Imprimer Modulel 
Option Explicit 
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I Sub Li rePropImprimanteO 
Dim monDocument As Object, imprimante As Variant 
Dim papVal As Integer, papTaille As Object 
Dim liste As String, cr As String 
Const twipsParMm =56.7 

cr = chr(13) ' caractere de fin de ligne 
monDocument = Thi sComponent 
imprimante = monDocument . Pri nter 

printProps(imprimante) ' lister les noms de proprietes 

liste = "Norn : " & getPropVal (imprimante, "Name") & cr & _ 
"Occupee : " & getPropVal (imprimante, "IsBusy") & cr & _ 
"Orientation de papier modifiable : " & 

getPropVal (imprimante, "CanSetPaperOrientation") & cr & _ 
"Format de papier modifiable : " & 

getPropVal (imprimante, "CanSetPaperFormat") & cr & 
"Taille de papier modifiable : " & 

getPropVal (imprimante, "CanSetPaperSize") & cr 

papVal = getPropVal (imprimante, "PaperOrientation") 

if papVal = com. sun. star. view. PaperOrientation. PORTRAIT then 

liste = liste & "Orientation Portrait" & cr 
el se 

liste = liste & "Orientation Paysage" & cr 
end if 

papTaille = getPropVal (imprimante, "PaperSize") 
papVal = getPropVal (imprimante, "PaperFormat") 
Select Case papVal 

Case com .sun. star. view. PaperFormat . A4 

liste = liste & "Format A4" 
Case com . sun . star . view . PaperFormat . LETTER 

liste = liste & "Format Letter" 
Case com . sun . star . view . PaperFormat . USER 

liste = liste & "Format inconnu : " 
Case Else 

liste = liste & "Autre format connu" 
end Select 
liste = liste & cr & _ 

"Hauteur : " & Format(papTaille.Height/twipsParMm, "0.#") & " mm" & cr & 
"Largeur : " & Format (papTaille.Width/twipsParMm, "##0.#") & " mm" 

MsgBox(liste, 0, "Capacites de 1 'imprimante") 

End Sub 
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La propriete Printer de l'objet document est un tableau de proprietes. La routine 
printProps balaie ce tableau, recupere le nom de chacune, avec l'index dans le 
tableau, puis affiche la liste. 

rem Code07-01.odt bibli : Imprimer Modulel 

Sub printProps(descr As Variant) 
Dim x As Long, liste As String 
liste = "" 

for x = 0 to UBound(descr) 

liste = liste & "Index " & x & " : " & descr(x) . Name & chr(13) 
next 

MsgBox(liste, 0, "Tableau de proprietes") 
End Sub 

Pour recuperer la valeur d'une propriete particuliere, il faut la rechercher dans le 
tableau de proprietes. La difficulte est que l'ordre des proprietes contenues dans le 
tableau obtenu par la propriete Printer depend de 1'implementation. Pour la con- 
tourner, nous utiliserons la fonction utilitaire getPropVal, detaillee a l'annexe B ; elle 
est recopiee dans la bibliotheque Standard du document. Cette fonction recupere la 
valeur de la propriete a partir de son nom. S'il n'existe pas de propriete a ce nom, elle 
declenche une erreur. Respectez toujours la casse (majuscules, minuscules) pour le 
nom d'une propriete. 

Dans le document ou se trouve la macro principale, ouvrez le menu Fichier>Parame- 
trage de I'imprimante... pour changer les caracteristiques d'impression. Relancez la 
macro, vous devriez pouvoir ainsi passer par les differents cas prevus. 



Changer la configuration d'impression 

II est possible de changer d'imprimante et, dans la mesure ou elle le permet, vous 
pouvez imposer les valeurs de ses proprietes. Dans cet exemple, nous changeons 
d'imprimante et imposons le format de papier Letter en orientation Paysage. 

rem Code07-01.odt bibli : Imprimer Module2 
Option Explicit 

Sub ChangerlmprimanteO 

Dim monDocument As Object, imprimante As Variant, nomlmpr As String 

monDocument = Thi sComponent 

imprimante = monDocument . Printer 

nomlmpr = InputBox("Nom de I'imprimante ?" 

setPropVal (imprimante, "Name", nomlmpr) 
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setPropVal (imprimante, "PaperFormat" , 

com . sun . star . vi ew. PaperFormat . LETTER) 
setPropVal (imprimante, "PaperOrientation" , 

com . sun . star . vi ew . Pape rOri entati on . LANDSCAPE) 

monDocument . Printer = imprimante 

Li rePropImprimante() ' lister les noms de proprietes 
End Sub 

Nous modifions le tableau de proprietes avec la routine utilitaire setPropVal decrite a 
1'annexe B, et recopiee dans la bibliotheque Standard du document. Elle recherche la 
propriete du nom donne en argument, et la modifie. Une fois le tableau modifie, il est 
copie dans la propriete Pri nter de l'objet document. Si vous repondez a la question avec 
un nom d'imprimante inexistante, le document reviendra sur 1'imprimante par defaut. 

Si votre imprimante accepte les changements de format et d'orientation de page, le 
format de page en cours sera modifie. Vous pouvez le verifier en ouvrant le menu 
Format>Page..., onglet Page. 

Pour une imprimante reseau, suivant la configuration en place, il peut etre necessaire 
d'entourer le nom de 1'imprimante avec les symboles < et > comme ceci : 

nomlmpr = "<ImprFi nanci er>" 



Lancer l'impression 

L'impression d'un document se fait au moyen de sa methode pri nt, qui a pour argu- 
ment un tableau contenant les options d'impression desirees (voir tableau 7-8). 

Tableau 7-8 Options d'impression 



Propriete Type Signification 


Fi 1 eName 


Stri ng 


Le nom du fichier d'impression, si on utilise cette possibility. 


CopyCount 


Integer 


Nombre d'exemplaires a imprimer. Par defaut : 1 


Collate 


Boolean 


True si on imprime les copies multiples document par document (valeur par defaut). 
Fal se si on imprime toutes les copies d'une page avant de passer a la page sui- 
vante. 


Pages 


Stri ng 


Indique les pages a copier, comme dans I'interface utilisateur. Exemple : 1 -4;1 0;1 5-1 8 
Par defaut : toutes les pages sont imprimees. 


Wait 


Boolean 


True : la methode print attend la fin de la mise en file d'attente d'impression. 
Fal se : la methode print envoie l'impression et retourne sans attendre (valeur par 
defaut). 
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Un petit exemple, a recopier dans un document suffisamment gros : 

rem Code07-01 . odt bibli : Imprimer Module3 
Option Explicit 

Sub ImprimerPartieO 

Dim monDocument As Object 

Dim Props (1) As New com. sun. star. beans. PropertyVal ue 

monDocument = Thi sComponent 
Props (0) .Name = "Pages" 
Props(O) .Value = "3; 15" 
Props (1) . Name = "Wait" 
Props (1) .Value = True 
monDocument . pr i nt (Props () ) 
End Sub 

Mettez a True la propriete Wai t si le document doit etre ferme immediatement apres 
le lancement de l'impression. 

Si vous executez cette macro sur un document d'une seule page, il ne se passera rien 
puisqu'aucune des pages demandees n'existe. 

Si on se contente de toutes les valeurs par defaut, il faut neanmoins fournir un 
tableau sans dimension, declare ainsi : 

Dim PropsO 

Nous venons de voir l'essentiel pour ouvrir, sauver, imprimer et fermer un document. 
Le reste du chapitre traite de sujets plus specialises. Vous pouvez preferer sauter a un 
chapitre propre a Writer, ou Calc, ou Draw/Impress. 



Enumerer les documents OpenOffice ouverts 

L'objet StarDesktop est un conteneur de tous les documents ouverts d'Open- 
Office.org. La macro suivante montre comment acceder successivement a tous les 
documents ouverts et les fermer (sauvegardez vos documents avant d'executer la 
macro). N'ouvrez pas l'EDI pour lancer cette macro, mais utilisez plutot le menu 
Outils>Macros>Executer la macro. 

rem Code07-04 . odt bibli : LeDocument Module4 
Option Explicit 

Sub BoucleFermeDocumentsO 
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'pensez a sauvegarder vos documents 
dim lesDocs, 1 aColl ecti on , leDoc 

on error resume next 

lesDocs = StarDesktop. Components 
laCollection = lesDocs.createEnumeration 

whi 1 e 1 aCol 1 ecti on . hasMoreEl ements 

leDoc = laCollection.nextElement 

print "Fermeture du document " & leDoc.URL 

leDoc. close (True) 
wend 

End Sub 

La pseudo-propriete Components de l'objet StarDesktop permet d'acceder a la collec- 
tion des documents ouverts. La methode createEnumeration renvoie un objet servant 
a enumerer les objets de cette collection. Le principe de parcours est base sur les deux 
methodes hasMoreEl ements (reste-t-il des elements a explorer?) et nextElement 
(acceder a l'element suivant que nous mettons dans la variable 1 eDoc). Pour chaque ele- 
ment, nous affichons son URL et envoyons une commande de fermeture. 

Cette methode peut etre utile pour fermer OpenOffice.org (ce qui revient a fermer 
tous les documents ouverts) a deux exceptions pres : 

• Si l'EDI est ouverte - Le composant contenant l'EDI ne se ferme pas comme un 
document classique, mais en utilisant leDoc.dispose(). Ceci justifie la presence 
de la ligne on error resume next permettant de poursuivre le traitement en cas 
d'erreur. 

• Sous Windows, si le lanceur rapide est en cours d'execution - Seules les fenetres 
d'OpenOffice.org seront fermees et le programme restera en cours d'execution. 



Les filtres d'import/export 

Les filtres d'importation servent a convertir un document d'un format autre que ceux 
d'OpenOffice.org vers un des formats d'OpenOffice.org. Les filtres d'exportation per- 
mettent d'enregistrer un document OpenOffice.org dans un autre format. Avant de 
vous lancer dans un projet Basic pour convertir des series de documents, consultez le 
site OOo Converter (http://oooconv.free.fr/) gere par un des auteurs de ce livre. II vous 
propose un tel outil, disponible en telechargement ou utilisable directement en ligne. 
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L'importation ou exportation consiste a charger ou sauvegarder un document en uti- 
lisant l'option FilterName pour preciser, sous forme de chaine de caracteres, le nom 
du filtre a employer. Ce nom doit etre recopie exactement. Certains filtres peuvent 
necessiter des parametres, qui sont transmis dans l'option FilterOptions ou dans 
l'option Filter-Data. 



Exporter ou importer un document dans un format particulier 

Pour charger un document d'un format OpenOffice.org ou d'un format concurrent, 
l'option FilterName est en general inutile car OpenOffice.org est assez intelligent 
pour trouver le filtre adequat. Sinon on precise le filtre d'importation a employer. 
Une fois le document charge, il est considere comme un document OpenOffice.org. 

Une sauvegarde storeAsURL ou storeToURL sans l'option FilterName produira un 
fichier au format par defaut defini par le menu Outils>Options>OpenOffice.org>Charge- 
ment/Enregistrement>General. Autrement dit, le format utilise pour le chargement 
n'est pas re-utilise par defaut dans un storeAsURL ou storeToURL : il est necessaire de 
le preciser avec l'option FilterName. II est souhaitable de donner une extension de 
fichier correspondant au format demande, bien que ceci n'ait aucune influence sur le 
format obtenu. 

Ceci s'applique en particulier pour sauvegarder dans un des formats OpenOffice.org, 
actuel ou ancien. Le tableau 7-9 liste les noms de filtres pour les formats Open- 
Office.org, valables pour l'importation comme pour 1' exportation. 

Tableau 7-9 Filtres des formats de documents OpenOffice.org 
Type de document Extension Nom du filtre 



Document Writer OpenOffice.org 1 


. sxw 


StarOffice XML (Writer) 


Modele Writer OpenOffice.org 1 


. stw 


wri ter_StarOff i ce_XML_Wri ter_Templ ate 


Document maTtre Writer 
OpenOffice.org 1 


. sxg 


wri ter_gl obal document_StarOff i ce_XML_Wri ter 


Document Writer/Web 
OpenOffice.org 1 


. html 


wri ter_web_StarOffi ce_XML_Wri ter 


Modele Writer/Web 
OpenOffice.org 1 


. stw 


wri ter_web_StarOf fi ce_XML_Wri ter_Web_Templ ate 


Document TexteODF 


.odt 


wri ter8 


Modele Texte ODF 


.ott 


wri te r8_templ ate 


Document maTtre ODF 


.odm 


wri tergl obal 8_writer 


Document Writer/Web 
OpenOffice.org 2 et 3 


.html 


wri terweb8_wri ter 
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Tableau 7-9 Filtres des formats de documents OpenOffice.org (suite) 



Type de document Extension Norn du filtre 


Modele Writer/Web 
OpenOffice.org 2 et 3 


.oth 


wri terweb8_wri ter_templ ate 


Document Calc OpenOffice.org 1 


. sxc 


StarOffice XML (Calc) 


Modele Calc OpenOffice.org 1 


.stc 


cal c_StarOf f i ce_XML_Cal c_Templ ate 


Document Classeur ODF 


.ods 


calc8 


Modele Classeur ODF 


. ots 


cal c8_templ ate 


Document Draw OpenOffice.org 1 


.odg 


StarOffice XML (Draw) 


Modele Draw OpenOffice.org 1 


. sxd 


draw_StarOff i ce_XML_Draw_Templ ate 


Document Dessin ODF 


.std 


draw8 


Modele Dessin ODF 


.otg 


draw8_template 


Document Impress OpenOffice.org 1 


. sxi 


StarOffice XML (Impress) 


Modele Impress OpenOffice.org 1 


. sti 


i mpress_StarOf f i ce_XML_Impress_Templ ate 


Documentation Presentation ODF 


.odp 


impress8 


Modele Presentation ODF 


.otp 


i mpress8_templ ate 



Le tableau 7-10 liste les principaux filtres pour importer ou exporter des documents 
dans d'autres formats. Certains formats comme MacroMedia-Flash ou PDF sont seu- 
lement disponibles a 1' export ; dans ce cas seule la methode storeToURL est autorisee. 

Tableau 7-10 Principaux filtres pour documents non OpenOffice.org 



Excel 2007 binaire 


import 


.xlsb 


Calc MS Excel 2007 Binary 


Excel 2007 XML 


import 


. xl sm 
. xl sx 


Calc MS Excel 2007 XML 


Modele de document Excel 2007 XML 


import 


. xl tm 
.xltx 


Calc MS Excel 2007 XML Template 


Excel 97 




.xls 


MS Excel 97 


Modele de document Excel 97 




.xlt 


MS Excel 97 Vorl age/Tempi ate 


Excel pocket 




. pxl 


Pocket Excel 


Word 2007 XML 


import 


.docx 
.docm 


MS Word 2007 XML 


Modele de document texte Word 2007 XML 


import 


. dotx 
.dotm 


MS Word 2007 XML Template 


Word 97 




.doc 


MS Word 97 


Modele de document Word 97 




.dot 


MS Word 97 Vorl age 
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Tableau 7-10 Principaux filtres pour documents non OpenOffice.org (suite) 



Word 6 




.doc MS WinWord 6.0 


Word 5 


import 


.ode 


MS WinWord 5 


Word pocket 




. psw 


PocketWord File 


PowerPoint 200/ XML 


import 


. pptm 

. DPtX 


Impress MS PowerPoint 2007 XML 


Modele de document PowerPoint 2007 XML 


import 


. potm 
. potx 


Impress MS PowerPoint 2007 XML 
Tempi ate 


PowerPoint 97 




■PPt 

. DOS 


MS PowerPoint 97 


Modele de document PowerPoint 97 




. pot 


MS PowerPoint 97 Vorlage 


WordPerfect 


import 


. wpd 


WordPerfect 


Format RTF depuis/vers Writer 




. rtf 


Rich Text Format 


Format RTF vers Calc 


import 


.rtf 


Rich Text Format (StarCalc) 


Texte non formate, caracteres encodes selon 
le systeme d'exploitation. 




. txt 


Text 


Texte non formate, I'encodage de caracteres 
est precise par une option. 


voir 
texte 


.txt 


Text (encoded) 


HTML 




. html 


HTML 


HTML depuis/vers Writer 




. html 


HTML (StarWriter) 


HTML depuis/vers Calc 




. html 


HTML (StarCalc) 


Lotus 1-2-3 


voir 
texte 


.wkl 
. wks 


Lotus 


Lotus 1-2-3 Windows 


voir 
texte 


.wkl 
. wks 


Lotus 1-2-3 1.0 (WIN) 
(StarWriter) 


Lotus 1-2-3 DOS 


voir 
texte 


.123 


Lotus 1-2-3 1.0 (DOS) 
(StarWriter) 


Format Unified Office, texte 




. uot 


UOF text 


Format Unified Office, tableur 




. UOS 


UOF spreadsheet 


Format Unified Office, presentation 




. uop 


UOF presentation 


AportisDoc (Palm) 




.pdb 


AportisDoc Palm DB 


Data Interchange Format 


voir 
texte 


.dif 


DIF 


DocBook 




. xml 


DocBook File 


Texte au format CSV 


voir 
texte 


. CSV 

.txt 


Text - txt - csv (StarCalc) 



Manipuler les documents OpenOffice.org 

Troisieme partie 

Tableau 7-10 Principaux filtres pour documents non OpenOffice.org (suite) 



Type de document 








Table dBase depuis/vers Calc 


voir 
texte 


.dbf 


dBase 


Draw vers Adobe Flash 




. swf 


draw_flash_Export 


Impress vers Adobe Flash 




. swf 


impress_flash_Export 


LaTeX 2e 


export 


. tex 


LaTeX_Writer 


MediaWiki 


export 


.txt 


Medi awi ki 


MediaWiki 


export 




Medi aWi ki_Web 



A titre d'exemple, ce codage exporte le document texte en cours vers le format RTF. 



rem Code07-05 . odt bibli : Standard Modulel 
Option Explicit 

Sub converti rVersRTFO 

Dim monDocument As Object, adresseDoc As String 

Dim props(O) As New com . sun . star . beans . PropertyVal ue 

monDocument = Thi sComponent 
props(O) . Name = "Filter-Name" 
props(O) .Value = "Rich Text Format" 

adresseDoc = convertToURL("C:\Docs OpenOffice\exemplel.rtf") 
monDocument . s to reToURL (adresseDoc , propsO) 
MsgBox("Termi ne ! ") 
End Sub 

Pour certains filtres, il faut preciser des options specifiques. Nous allons les detailler ci- 
apres. Mais sachez que, si vous mettez un InteractionHandler dans les options de 
chargement ou sauvegarde de fichier (comme dans l'exemple du mot de passe prece- 
demment), le dialogue approprie apparaitra pour que l'utilisateur choisisse les options. 

Pour les filtres dBase, DIF, Lotus, le parametre Fi IterOptions accepte une chaine 
precisant le jeu de caracteres. Le tableau 7-17, colonne « valeur pour un filtre CSV », 
indique les valeurs pour les jeux de caracteres les plus courants. 

Exporter en PDF 

Le tableau 7-11 liste les differents filtres disponibles. 

II existe de nombreuses options pour une exportation en PDF. Nous nous baserons 
sur l'excellent article en anglais http://wiki.services.openoffice.org/wiki/API/Tutorials/ 
PDF_export qui liste les options dans le meme ordre que sur l'interface utilisateur, 
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onglet par onglet. Ces options sont decrites dans les tableaux 7-12 a 7-16. Quand 
une propriete de type Bool ean correspond a une case a cocher, la valeur True equivaut 
a cocher la case. Les options de securite (tableau 7-16) ne sont pas utilisees pour une 
exportation en PDF/Al. 



Tableau 7-11 Filtres d'exportation en PDF 




cal c_pdf_Export 



draw_pdf_Export 

impress_pdf_Export 

math_pdf_Export 

wri ter_gl obal document_pdf_Export 
wri ter_pdf_Export 
wri ter_web_pdf_Export 

Sauf indication specifique, les valeurs par defaut sont Fal se et zero. Mais attention : 
ces valeurs par defaut d'origine sont en pratique rarement utilisees ! En effet Open- 
Office. org memorise les dernieres valeurs choisies par l'interface utilisateur (export 
PDF manuel), et les utilise comme valeurs par defaut pour les prochains exports 
PDF, y compris par l'API. Vous avez done interet a remplir toutes les valeurs qui 
vous sont utiles. 



Tableau 7-12 Options PDF - Onglet General 



Propriete 




Equivalent pour l'interface utilisateur 


PageRange 


Stri ng 


Plage>Pages : la ou les pages a exporter, exemple 1-3;10 
Mettre une chame vide pour exporter toutes les pages. 


Selection 


Object 


Objet correspondant a la selection visuelle d'une zone. 


UseLosslessCompression 


Boolean 


True correspond a : lmages>Compression sans perte 
Fal se correspond a : lmages>Compression JPEG 


Quality 


Long 


lmages>Compression JPEG>Qualite 

Valeur du pourcentage de compression, de 1 a 1 00. Valeur par 

defaut : 90 


ReducelmageResol uti on 


Boolean 


lmages>Reduire la resolution des images 

True pour reduire la resolution de chaque image a celle indiquee 

dans MaxImageResol uti on. 


MaxImageResol uti on 


Long 


Liste de choix de resolution DPI 

Valeurs possibles (en DPI) : 75, 150, 300, 600, 1200. Valeur par 
defaut : 300. 
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Tableau 7-12 Options PDF - Onglet General (suite) 
jivalent pour Tin 



Sel ectPdfVersion 


Long 


General>PDF/A-1 

Version du codage PDF, valeurs possibles : 

0 pour PDF 1.4 (equivalent a la case non cochee dans I'interface uti- 
lisateur) 

1 pour PDF/A-1 (equivalent a la case cochee) 


UseTaggedPDF 


Boolean 


General>PDF marque 
(non utilise en PDF/A-1) 


ExportFormFields 


Bool ean 


General>Creer un formulaire PDF 

(non utilise en PDF/A-1) Valeur par defaut : True. 


FormsType 


Long 


General>Creer un formulaire PDF>Format d'envoi 
(non utilise en PDF/A-1), valeurs possibles : 

0 pour FDF 

1 pour PDF 

2 pour HTML 

3 pour XML 


ExportBookmarks 


Boolean 


General>Exporter les reperes de texte 

True correspond a la case cochee. Valeur par defaut : True. 


ExportNotes 


Boolean 


General>Exporter les notes 

II s'agit des notes jaunes de Writer et Calc. 


Expo rtNotes Pages 


Boolean 


General>Exporter les notes 

II s'agit des pages de notes d'lmpress. 


IsSki pEmptyPages 


Boolean 


General>Exporter automatiquement les pages blanches 
inserees 

Ne concerne que Writer. 


Tableau 7-13 Options PDF - Onglet Vue initiale 




Type Equivalent pour I'interface utilisateur 


InitialVi ew 


Long 


Volets>(choix ) 
0 : Page uniquement 

1 : Reperes de texte et page 

2 : Miniatures et pages 


Initial Page 


Long 


Volets>Ouvrir dans la page 

Numero de la page a afficher. Valeur par defaut : 1 . 


Magnification 


Long 


Agrandissement>(choix) 

0 : Par defaut (configuration du lecteur PDF) 

1 : Adapter a la fenetre 

2 : Adapter la largeur 

3 : Adapter au visible 

4 : Facteur de zoom (voir la propriete Zoom) 
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Tableau 7-13 Options PDF - Onglet Vue initiale (suite) 



Zoom 


Long 


Agrandissement>valeur du zoom 

Valeur 50 pour un zoom a 50%. Valeur par defaut : 100. 


PageLayout 


Long 


Mise en page>(choix) 

0 : Par defaut (configuration du lecteur PDF) 

1 : Une page 

2 : Continu (pages se succedant en colonne continue) 

3 : Orientation continue (deux pages a la fois, par defaut page paire 
a gauche et impaire a droite) 


Fi rstPageOnLeft 


Boolean 


(Non disponible dans I'interface utilisateur) 

Dans le cas PageLayout = 3, True affiche la premiere page (page 

impaire) a gauche. 



Tableau 7-14 Options PDF - Onglet Interface utilisateur 





Resi zeWi ndowToIni ti al Page 


Boolean 


Option de fenetre>Redimensionner la fenetre selon la 
page initiale 


CenterWi ndow 


Boolean 


Option de fenetre>Centrer la fenetre sur I'ecran 


OpenlnFul 1 ScreenMode 


Bool ean 


Option de fenetre>Ouvrir en mode plein ecran 


Di spl ayPDFDocumentTi tl e 


Boolean 


Option de fenetre>Afficher le titre du document 
Valeur par defaut : True. 


Hi deVi ewerMenubar 


Boolean 


Options d'interface utilisateur>Masquer la barre de 
menu 


Hi deVi ewerTool bar 


Boolean 


Options d'interface utilisateur>Masquer la barre 
d'outils 


Hi deVi ewerWi ndowControl s 


Boolean 


Options d'interface utilisateur>Masquer les controles 
de fenetre 


UseTransi ti onEf f ects 


Boolean 


Transitions>Utiliser les effets de transition 


OpenBookmarkLevel s 


Long 


Reperes de texte>(choix) 

-1 : Tous les niveaux de reperes de texte (valeur par defaut) 
1 a 1 0 : Niveaux de reperes de texte visible 



Tableau 7-15 Options PDF - Onglet Liens 



Propriete Type Equivalent pour I'interface utilisateur 


ExportBookmarksToPDFDesti nation 


Boolean 


Exporter les reperes de texte comme destina- 
tions nominees 

(voir specification du PDF 1.4 section 8.2.1) 
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Driete 



Tableau 7-15 Options PDF - Onglet Liens (suite) 
Type 



ConvertOOoTargetToPDFTarget 


Boolean 


Convertir les references de document en cibles 
PDF 

True : les hyperliens referencent des fichiers pdf au 
lieu des fichiers odt, ods, etc. 


ExportLi nksRelativeFsys 


Boolean 


Exporter les URL relatives au systeme de fichiers 
True : les hyperliens sont en adresses relatives a ce 
document. 


PDFViewSelection 


Long 


Liens entre documents>(choix) 

0 : Mode par defaut (traiter ces liens comme des URI) 

1 : Ouvrir avec un lecteur de PDF (non utilise en PDF/A-1) 

2 : Ouvrir avec un navigateur 



Tableau 7-16 Options PDF - Onglet Securite 



Propriete 

EncryptFi le 


Tvnp 

Bool ean 


Bouton Def.mot de passe d'ouverture... 


DocumentOpen Password 


Stri ng 


Mot de passe d'ouverture 


Restri ctPermi ssi ons 


Bool ean 


Bouton Def. mot de passe d'autorisation 


Permi ssionPassword 


Stri ng 


Mot de passe d'autorisation 


Pri nti ng 


Long 


lmpression>(choix) 
Valeurs possibles : 
0 : Non autorise 

1 : Faible resolution 

2 : Haute resolution (valeur par defaut) 


Changes 


Long 


Modifications>(choix) 
Valeurs possibles : 
0 : Non autorise 

1 : Insertion, suppression et rotation de pages 

2 : Remplissage de champs de formulaire 

3 : Insertion de commentaires, remplissage de 
champs de formulaire 

4 : Tout sauf I'extraction de pages (valeur par 
defaut) 


Enabl eCopyi ngOf Content 


Bool ean 


Modifications>Autoriser la copie de 
contenu 

Valeur par defaut : True. 


Enabl eTextAccessForAccessi bi 1 i tyTool s 


Bool ean 


Modifications>Autoriser I'acces au texte 
des outils d'accessibilite 
Valeur par defaut : True. 
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Exemple d'export PDF 

Les options de storeToURL sont declarees dans un tableau de PropertyVal ue. Les 
options d'export PDF doivent etre aussi declarees dans un autre tableau de 
PropertyVal ue, et ce tableau transmis comme valeur de l'option FilterData du pre- 
mier tableau. Nous avons vu la lourdeur de ces declarations de tableaux de 
PropertyVal ue, ici nous emploierons une fonction simplificatrice, 
CreateProperties, decrite a 1' annexe B. Cette fonction comporte un argument, qui 
est un tableau cree avec la fonction Array. Les arguments d'Array sont en nombre 
pair : le nom d'une propriete, suivi de sa valeur, le nom d'une autre propriete, sa 
valeur, etc. La fonction CreateProperties renvoie un tableau de PropertyVal ue 
completement initialise. 

Pour simplifier cet exemple, seules les proprietes ayant des valeurs autre que defaut 
sont initialisees ; l'ordre de declaration des proprietes est sans importance. Rappelons 
qu'il faut respecter la casse pour tous ces noms de proprietes ! 

rem Code07-05 . odt bibli : Standard Module2 
Option Explicit 

Sub converti rVersPDFO 

Dim monDocument As Object, adresseDoc As String 
Dim props As Variant, propsFiltre As Variant 

monDocument = Thi sComponent 
propsFiltre = CreateProperties(Array( 

"Quality", 30, 

"ReducelmageResol ution" , True, "MaxImageResol ution" , 75, _ 
"UseTaggedPDF" , True, _ 
"FormsType", 1, _ 
"ExportNotes" , True, _ 
"InitialView", 1, "PageLayout" , 3, 
"DisplayPDFDocumentTitle", False, 
"PDFViewSelection" , 1)) 
props = CreateProperties(Array( 

"Fil terName" , "wri ter_pdf_Export" , "FilterData", propsFi 1 tre() )) 

adresseDoc = convertToURL("C:\Docs OpenOffice\exemple2.pdf") 
monDocument. storeToURL(adresseDoc, propsO) 
MsgBox("Termi ne ! ") 
End Sub 



BOGUE Export PDF depuis I'EDI 

Le rapport d'anomalie Issue 89389 signale que les liens ne sont pas conserves dans le fichier PDF obtenu, 
si la macro est lancee depuis I'EDI ! Lancez done la macro d'exportation depuis la fenetre du document. 
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Importer un document PDF 

L'importation du format PDF ne se fait pas par un filtre mais avec 1' extension Sun 
PDF Import disponible sur Internet : 

http://extensions.services.openoffice.org/project/pdfimport 

Importer et exporter au format CSV 

Les formats CSV (de 1' anglais Comma Separated Values) sont des formats en texte pur 
(non formate) dont chaque ligne comporte plusieurs champs, separes les uns des autres 
avec une convention particuliere. Par exemple, le separateur de champ sera une virgule 
ou un caractere de tabulation. Chaque ligne est l'equivalent d'un enregistrement au 
sens des bases de donnees. Les fichiers au format CSV servent souvent de format 
intermediate entre deux applications ayant des formats de fichier incompatibles. 

Le filtre CSV necessite cinq parametres qu'il faut compacter dans une simple chaine 
de caracteres afin de pouvoir l'affecter a l'option Fi 1 terOpti ons. 

Les parametres du filtre CSV 
Parametre 1 : le separateur de champ 

Dans le cas general, le separateur de champ est un caractere. Neanmoins, seule sa 
valeur numerique ASCII sera utilisee, et ceci sous forme de chaine de caracteres. 

Le caractere Tabulation a pour valeur 9, le caractere Virgule a pour valeur 44. Pour 
tout caractere imprimable, une ligne Basic peut nous donner sa valeur ASCII. Par 
exemple, pour une virgule : 

print Asc(",") 

Si plusieurs separateurs sont acceptables, on les separera par le caractere barre de 
fraction. Par exemple, tabulation et virgule donneront un parametre : 

PI = "9/44" 

Si le separateur est constitue par plusieurs caracteres consecutifs, on ajoute a droite la 
sequence MRC ainsi : 



' separateur $$ 
PI = "36/36/MRC" 



Les documents OpenOffice.org 

Chapitre 7 



Enfin, au lieu d'utiliser un caractere separateur, on peut fixer le nombre de caracteres 
de chaque champ : on parle de champs fixes. Le parametre s'ecrit : 



I 



PI 



■FIX" 



Parametre 2 : le delimiteur de champ texte 

Un champ texte pouvant comporter divers caracteres, il est encadre a gauche et a 
droite par un caractere ne se trouvant pas dans le texte. Habituellement, on emploie 
le caractere guillemet " (valeur 34) ou le caractere apostrophe ' (valeur 39). 

Le parametre 2 contient la valeur decimale du caractere delimiteur de texte. 



P2 



'39' 



Parametre 3 : le jeu de caracteres utilise 

Comme le fichier CSV ne contient que des caracteres codes sur un octet, la represen- 
tation des caracteres nationaux depend du jeu de caracteres utilise. Le parametre 3 
contient une chaine de caracteres designant le jeu employe. Le tableau 7-17, colonne 
« valeur pour un filtre CSV », indique les valeurs pour les jeux de caracteres les plus 
courants en Europe. 

Notre fichier exemple est ecrit sous Windows- 1252, done le parametre 3 vaut ANSI. 
Si la macro est executee sous MS-Windows, e'est aussi le jeu de caracteres du systeme. 

P3 = "ANSI" 



Jeu de caracteres 



Tableau 7-17 Principaux jeux de caracteres pour les filtres 

Valeur pour filtre CSV Valeur pour 



Europe occidentale (ASCII/US) 


11 


ASCIIJJS 


Europe occidentale (DOS/OS2-437/US) 


IBMPC_437 


IBM_437 


Europe occidentale (DOS/OS2-850/lnternational) IBMPC_850 


IBM_850 


Europe occidentale (DOS/OS2-863/Francais canadien) 


IBMPC_863 


IBM_863 


Europe occidentale (Windows-1252/WinLatin1) 


ANSI 


MS_1252 


Europe occidentale (Apple Macintosh) 


MAC 


APPLE_ROMAN 


Europe occidentale (ISO-8859-1) 


12 


ISO_8859_l 


Latin 3 (ISO-8859-3) 


14 


ISO_8859_3 


Europe occidentale (ISO-8859-1 4) 


21 


IS0_8859_14 


Europe occidentale (ISO-8859-1 5/EURO) 


22 


ISO_8859_15 


Unicode (16 bits) 


65535 


UCS2 
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Tableau 7-1 7 Principaux jeux de caracteres pour les filtres (suite) 



Jeu de caracteres Valeur pour filtre CSV Valeur pour 


Unicode (UTF-8) 


76 


UTF8 


Systeme (son jeu de caracteres natif) 


0 


0 


Le jeu de caracteres du systeme est aussi utilise pour 
toute valeur non reconnue 


XXX 


XXX 



Parametre 4 : premiere ligne a traiter 

Souvent, un fichier CSV comporte une ou plusieurs lignes d'en-tete avant les lignes 
de donnees. Ce parametre precise le numero de la premiere ligne a traiter, la pre- 
miere ligne du fichier ayant le numero 1. Exemple : 



P4 = "2" 

Parametre 5 : format de chaque colonne 

II est necessaire de preciser le format des donnees pour chaque champ. Le parametre 
est alors constitue d'une sequence de caracteres comportant : 

1 le rang du champ (le premier champ a pour rang 1) ; 

2 un caractere / ; 

3 un nombre indiquant le format du champ ; 

4 un caractere / avant la description de format du champ suivant. 
Les valeurs de format possibles sont les suivantes : 

1 standard (en importation, Calc decide du format) ; 

2 texte ; 

3 MM/DD/YY (mois, jour, an, deux chiffres chacun) ; 

4 DD/MM/YY (jour, mois, an, deux chiffres chacun) ; 

5 YY/MM/DD (an, mois, jour, deux chiffres chacun) ; 

9 ignorer ce champ ; 

10 nombre a l'americaine : point decimal et virgule comme separateur de milliers. 
Le format 10 a priorite sur un format de nombre national. 

Exemple pour quatre champs : 

P5 = "1/1/2/5/3/2/4/2" 
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Dans le cas parti culier d'un format FIX (voir parametre 1), le parametre 5 contient, 
pour chaque champ successivement, la position du premier caractere de ce champ, a 
partir de la position zero, un caractere / et la valeur de format. Exemple : 

P5 = "0/1/8/5/18/2/45/2" 

Constitution de la valeur de FilterOptions 

La valeur de Fi "IterOptions est done une chaine de caracteres constituee par la con- 
catenation des cinq parametres, separes par une virgule, soit : 

props(l) . Name = "FilterOptions" 

props(l) .Value = PI & "," & P2 & "," & P3 & "," & P4 & "," & P5 

Bien entendu, nous avons employe des variables intermediates pour clarifier un peu. 
On aurait pu ecrire directement : 

| props(l) .Value = "9 , 39 , ANSI , 2 , 1/1/2/5/3/2/4/2" 

Creer un document Calc a partir d'un CSV 

Nous allons importer un document texte au format CSV, et en faire un fichier Calc. 
Le document source a ete ecrit sous MS-Windows, et comporte quatre champs 
separes par une tabulation, les deux premiers sont des textes, le troisieme est un 
champ numerique entier ; le dernier champ est un nombre reel utilisant la virgule 
comme separateur decimal. Le delimiteur de texte est le guillemet. Vous pourrez 
vous amuser a verifier la chaine de caracteres pour FilterOptions, ou essayer 
d'autres variantes. 

rem Code07-06 . odt bibli : Standard Modulel 
Option Explicit 

Sub chargerCsvCommeCalc 

Dim propsl(l) As New com. sun. star. beans. PropertyValue 
Dim props2() 

Dim adrDocCSV As String, adrDocCalc As String 
Dim docCalc As Object 

adrDocCSV = ConvertToURL("C:\Docs OpenOffice\CSVexemplel.txt") 

propsl(O) .Name = "Filter-Name" 

propsl(O) .Value = "Text - txt - csv (StarCalc)" 

propsl(l) . Name = "FilterOptions" 

propsl(l). Value = "9, 34, ANSI, 1,1/2/2/2/3/1/4/1" 

docCalc = StarDesktop.loadComponentFromURL(adrDocCSV, "_blank", 0, propslQ) 
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adrDocCalc = ConvertToURL("C:\Docs OpenOffice\resultatCSV.ods") 
docCalc.storeAsURL(adrDocCalc, props2() ) 
End Sub 

Une fois l'importation effectuee, un fichier Calc apparait, qui n'est que la visualisa- 
tion du document texte CSV. Pour obtenir un vrai document Calc, on utilise 
storeAsURL ou storeToURL avec les options par defaut. 

Importer un CSV dans une feuille de Calc 

On peut aussi importer le CSV dans une feuille d'un document Calc existant, avec la 
fonction de lien. Dans l'exemple suivant on importe le CSV dans la feuille existante 
« leCSV ». 

rem Code07-09.ods bibli : Standard Modulel 
Option Explicit 

Sub ChargerCsvDansFeui 1 1 e() 

dim adrDocCSV as string, optFiltre as string 

dim docCalc as object, maFeuille as object 

docCalc = Thi sComponent 

maFeuille = docCal c . Sheets . getByName("l eCSV") 

adrDocCSV = ConvertToURL("C : \Docs OpenOffice\CSVexemplel.txt") 

optFiltre = "9 , 34 , ANSI , 1, 1/2/2/2/3/1/4/1" 

maFeuille. 1 i nk(adrDocCSV, "", "Text - txt - csv (StarCalc)", 
optFil tre , com . sun . star . sheet . Sheet Li nkMode . VALUE) 

' maintenant on peut casser le lien 

ImaFeui lie. set Li nkMode (com . sun . star . sheet . Sheet Li nkMode . NONE) 
End Sub 

Vous remarquerez que le contenu et le formatage de la feuille Calc sont totalement 
remplaces. 

Importer et exporter du texte pur 

Nous appelons ici « texte pur » un texte ordinaire, sans aucune marque de formatage. 
Si nous voulons une macro de lecture ou d'ecriture de fichier texte pur qui soit inde- 
pendante du systeme d'exploitation, il faut preciser le jeu de caracteres servant a 
l'encodage. Le filtre Text (encoded) comporte jusqu'a quatre parametres en carac- 
teres, separes par des virgules et mis dans une chaine : 

1 le jeu de caracteres, voir le tableau 7-17, colonne « Valeur pour texte encode » ; 



Les documents OpenOffice.org 

Chapitre 7 



2 les fins de lignes ; CRLF ou LF ou CR, respectivement pour les textes DOS/Windows, 
Unix/Linux, Macintosh ; 

3 la police de caracteres du document (seulement en importation), exemple DejaVu 
Serif ; 

4 la localisation du document (seulement en importation), exemple f r-CA. 
Ce qui donnerait, par exemple : 

props(l) . Name = "Fi 1 terOpti ons" 

props(l) .Value = "MS-1252 , CRLF, DejaVu Serif, fr-CA" 

On peut se limiter au premier ou deux premiers parametres. Dans 1' exemple suivant, 
on lit un texte Windows pour le convertir en un texte UTF-8 Unix. 

rem Code07-06.odt bibli : Standard Module3 
Option Explicit 

Sub conversionTexte 

Dim props(l) As New com. sun. star. beans. PropertyValue 

Dim adrDocTXT As String, adrdocWriter As String, docWriter As Object 

adrDocTXT = ConvertToURL("C:\Docs OpenOffice\TexteWinl252CRLF.txt") 
props(O) .Name = "FilterName" 
props (0) .Value = "Text (encoded)" 
props(l) .Name = "FilterOptions" 
props(l). Value = "MS-1252 , CRLF" 

docWriter = StarDesktop.loadComponentFromURL(adrDocTXT, "_blank", 0, propsO) 

adrDocTXT = ConvertToURL("C:\Docs OpenOffice\ResuUTF8LF.txt") 
props (1). Value = "UTF8, LF" 
docWriter.storeAsURL (adrDocTXT, props ()) 
End Sub 



Exporter une forme ou une image 

Nous appelons ici « forme » un dessin, eventuellement compose d'un groupement de 
dessins elementaires. Exporter une forme ou une image d'un document consiste a en 
obtenir un fichier image code dans un certain format. Ceci est possible en utilisant le 
service d'exportation qui a pour nom : 

com . sun . star . drawi ng . Graphi cExportFi 1 ter 
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II est capable de creer un fichier image a partir d'une page, d'une forme, d'une collec- 
tion de formes, d'une image. Ce service gere un certain nombre de types Mime ; leur 
nombre peut augmenter avec les nouvelles versions d'OpenOffice.org. Cette macro 
affiche la liste des types Mime supportes. 

rem Code07-08.ods bibli : ExportGraphi que Modulel 
Option Explicit 

Sub TisterTypesMimeExportO 

Dim serv As Object, liste As String, typeMime As String 

serv = CreateUnoServi ce("com . sun . star .drawn ng . Graphi cExportFil ter") 

liste = "- - Types Mime supportes - -" 

for each typeMime in serv.getSupportedMimeTypeNamesO 

liste = liste & chr(13) & typeMime 
next 

MsgBoxO i ste) 
End Sub 

Nous remarquons que rien dans cette macro nest specifique d'un document. La fonc- 
tion Basic CreateUnoServi ce nous fournit l'objet correspondant au service d'export 
graphique. La methode getSupportedMimeTypeNames de cet objet nous renvoie un 
tableau de chaines de caracteres. La boucle for each simplifie le balayage de ce 
tableau, on aurait pu employer un index. Le tableau 7-18 donne quelques informations 
sur les types Mime supportes. Notez que l'export en svg fonctionnait en version 1.1.5, 
mais ne fonctionne plus depuis la version 2.0 (voir le rapport Issue 58319). 



Tableau 7-18 Types Mime supportes 



Mime 


Format obtenu 


Couleurs 


Extension 


i mage/x-MS-bmp 


OS/2 - MS-Windows bitmap 


16 millions 


bmp 


appl i cati on/postscri pt 


Encapsulated Postscript 


16 millions 


eps 


image/gif 


Compuserve GIF 89a 


256 


gif 


i mage/ j peg 


JPEG version 1 


16 millions 


jpg- jpe, jpeg 


image/png 


Portable Network Graphic compresse 


16 millions 


png 


i mage/ti ff 


Tagged Image File Format compresse 


16 millions 


tif, tiff 


i mage/x-pi ct 


Mac Pict 


16 


pet 


i mage/x-portabl e-bi tmap 


Portable Bitmap 


2 


pbm 


i mage/x-portabl e-graymap 


Portable Graymap 


256 


pgm 


i mage/x-portabl e-pi xmap 


Portable Pixelmap 


16 millions 


ppm 


image/x- emu -raster 


Sun Raster image, type 2 


16 millions 


ras 


image/x-xpixmap 


X Xindows Pixmap 


256 


xpm 
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Tableau 7-18 Types Mime supportes (suite) 
lat obtenu 



image/x-emf 


Enhanced Metafile 


16 millions 


emf 


image/x-met 


OS/2 Metafile 


16 millions 


met 


image/x-svm 


Starview Metafile 


16 millions 


svm 


image/x-wmf 


MS-Windows Metafile 


16 millions 


wmf 


image/svg+xml 


Scalable Vector Graphics (voir texte) 


16 millions 


svg 



II est possible d'exporter une forme ou une image contenue dans un document Calc, 
Draw ou Impress. Depuis un document Writer il nest pas possible d'exporter une 
image, car cet objet n'a pas les caracteristiques necessaires, on peut cependant exporter 
une forme. Pour executer les macros qui suivent, selectionnez un seul dessin ou une 
seule image dans le document et executez la macro depuis le menu Outils. Dans les cha- 
pitres suivants, vous apprendrez comment obtenir par programmation un objet forme 
ou image dans un document sans qu'il soit necessaire de le selectionner. 

Pour exporter un objet forme (ou image), nous le mettons en argument de la 
methode setSourceDocument de 1' objet service. Notez que la pseudo-propriete 
SourceDocument ne fonctionne pas ici. Nous utilisons un tableau de PropertyVal ue : 
la propriete URL contient l'adresse du fichier a creer ; la propriete Filter-Name precise 
le filtre a employer sous la forme de l'extension de fichier. Ce tableau est transmis en 
argument a la methode filter de l'objet service, qui effectue le travail, et renvoie 
True s'il s'est bien effectue. 



rem Code07-08 . ods 
Option Explicit 



bibli : ExportCraphique Module2 



Sub exporterSelection_l() 

Dim monDocument As Object, maForme As Object 

Dim props (1) As New com. sun. star. beans. PropertyVal ue 

Dim serv As Object, typeMime As String, resultat As Boolean 

monDocument = Thi sComponent 

maForme = monDocument. CurrentSel ecti on (0) 

serv = CreateUnoSe rvice( "com. sun. star .drawing. GraphicExportFi Iter") 

serv. setSourceDocument(maForme) 
props(O) .Name = "URL" 

props(O) .Value = ConvertToURL("C : \Docs OpenOff i ce\monFichier") 
props(l) . Name = "FilterName" 
props(l) . Val ue ="emf" 

resultat = serv.filter(propsO) 
if resultat then 

MsgBox("Exportation termi nee") 
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el se 

MsgBox("Echec d ' exportati on" , 16) 
end "if 
End Sub 

Attention, l'exportation ecrase tout fichier du meme nom ! L'extension du fichier lui- 
meme peut etre quelconque, ici nous n'en n'avons pas. Mais si le fichier comporte une 
extension connue et que FilterName contient une valeur non reconnue, le service 
d'export choisira le filtre indique par l'extension du fichier ; le resultat n'est cependant 
pas toujours le meme (vu avec jpg), alors assurez-vous du contenu de Fi "IterName. 

Une autre methode d'export consiste a utiliser la propriete MediaType, de type 
String, pour preciser le filtre sous la forme du type Mime souhaite. Les remarques 
du cas precedent s'appliquent de meme ici. 

rem Code07-08 . ods bibli : ExportGraphi que Module3 
Option Explicit 

Sub exporterSelection_2() 

Dim monDocument As Object, maForme As Object 

Dim props(l) As New com . sun . star . beans . PropertyVal ue 

Dim serv As Object, typeMime As String, resultat As Boolean 

monDocument = Thi sComponent 

maForme = monDocument. CurrentSelection(O) 

serv = CreateUnoServi ce("com. sun . star . drawi ng .Craphi cExportFi 1 ter") 
serv . set Sou rceDocument (maForme) 
props(O) .Name = "URL" 

props(O) .Value = ConvertToURL("C:\Docs OpenOff i ce\monFichier") 
props(l) . Name = "MediaType" 
props (1) .Value ="image/x-emf " 

resultat = serv. fi lter(propsO) 
if resultat then 

MsgBox("Exportation termi nee") 
el se 

MsgBox("Echec d ' exportati on" , 16) 
end if 
End Sub 

Avec Draw/Impress, on peut exporter une page de dessin en donnant en argument 
de setSou rceDocument l'objet page. Pour exporter un ensemble de formes, nous 
devons les mettre dans un objet collection, comme il est indique au chapitre 10. II est 
inutile de les grouper effectivement. 

Certains filtres utilisent des parametres, helas non documented. Ces parametres sont 
transmis dans une propriete Fi IterData, sous la forme d'un tableau de PropertyVal ue. 
Void un exemple d'export en Jpeg de faible qualite et en niveaux de gris. 
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rem Code07-08 . ods 
Option Explicit 



bibli : ExportCraphique Module4 



Sub exporter] PEG_Options() 

Dim monDocument As Object, maForme As Object 

Dim props(2) As New com . sun . star . beans . PropertyVal ue 

Dim opts(l) As New com. sun. star. beans. PropertyVal lie 

Dim serv As Object, typeMime As String, resultat As Boolean 

monDocument = Thi sComponent 

maForme = monDocument. CurrentSelection(O) 

serv = CreateUnoServi ce("com . sun . star . drawi ng . Graphi cExportFi 1 ter") 
serv . setSourceDocument (maForme) 
props(O) .Name = "URL" 

props(O) .Value = ConvertToURL("C : \Docs OpenOffice\monFichier.jpg") 

props (1) . Name = "MediaType" 

props(l) .Value ="image/jpeg" 

opts (0). Name = "Quality" 

opts(O) .Value = 15 

opts (1) . Name = "ColorMode" 

opts(l) .Value = 1 

props (2) .Name = "FilterData" 

props(2) .Value = opts() 

resultat = serv.filter(propsO) 

if resultat then 

MsgBox("Exportation termi nee") 
el se 

MsgBox("Echec d ' exportati on" , 16) 
end if 
End Sub 

Le tableau 7-19 indique les parametres que nous avons pu trouver et verifier. La plupart 
correspondent aux options affichees dans un export manuel d'une image dans Draw. 

Tableau 7-19 Parametres de filtres d'export 



jpg 


Quality 


Integer 


De 1 (faible qualite, forte compression) a 100 (forte 
qualite, faible compression). 




Col orMode 


Integer 


0 : couleurs. 

1 : niveaux de gris. 


png 


Compression 


Integer 


0a9. 




Interlaced 


Long 


0 : non intrelace. 
1 : entrelace. 
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Tableau 7-19 Parametres de filtres d'export (suite) 



gif 


Inter! aced 


Long 


0 : non intrelace. 
1 : entrelace. 




Transl ucent 


Long 


0 : pas de transparence. 

1 : garder la transparence. 


jpg, gif, bmp, tif 


Pixel Width 


Long 


Largeur de I'image, en pixels. 




Pixel Height 


Long 


Hauteur de I'image, en pixels. 


eps 


Version 


Long 


1 : pas de choix de compression ni de couleur. 

2 : tous choix possibles. 




Previ ew 


Long 


0 : ni TIFF, ni EPSI. 

1 : TIFF. 

2 : EPSI. 

3 : TIFF et EPSI. 




Col orFortnat 


Long 


1 : couleurs. 

2 : niveaux de gris. 




CompressionMode 


Long 


1 : compression LZW 

2 : pas de compression. 


bmp 


Color 


Long 


0 : comme I'original. 
1 : valeur de seuil, 1 bit. 

5 ! niveaux de gris, 8 bits. 

6 : palette de couleurs, 8 bits. 

7 : couleurs 24 bits. 




RLE_Coding 


Bool ean 


True pour comprimer en RLE. 




ExportMode 


Long 


0 : comme I'original. 

1 : changer la resolution (Resol ution) verticale et 
horizontale. 

2 : changer la taille finale (Logi cal Hei ght et 
Logi calWi dth). 




Resolution 


Long 


Valeur en DPI. 




Logical Height 


Long 


Hauteur en 1/100 de mm. Ceci change le DPI vertical. 




Logical Width 


Long 


Largeur en 1/100 de mm. Ceci change le DPI horizontal. 


emf 


ExportMode 


Long 


0 : comme I'original. 

1 : changer la taille finale (Logi cal Hei ght et 
Logi calWi dth). 




Logical Height 


Long 


Hauteur en 1/100 de mm. 




Logical Width 


Long 


Largeur en 1/100 de mm. 
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Liste complete des filtres 



Le fichier ListeDesFiltres.ods est disponible dans le Zip telechargeable dans le 
sous-repertoire correspondant a ce chapitre. II permet d'obtenir la liste des filtres 
reconnus par votre version en cliquant sur le bouton Lister les filtres. La liste est triee 
en ordre alphabetique, et indique l'usage : importation, exportation, modele. Ces 
informations sont donnees par l'API, et la signification pour certains filtres n'est pas 
toujours claire. 

II existe peu de documentation sur les parametres des filtres. Pour les filtres d'impor- 
tation, le fichier ListeDesFiltres.ods permet d'obtenir la chaine a mettre dans 
FilterOptions. Vous devez disposer d'un fichier a importer. Selectionnez en 
colonne A le filtre d'importation correspondant et cliquez sur le bouton Options du 
filtre. La macro vous demande alors d'indiquer le fichier a importer. Les parametres 
necessaires sont ensuite demandes par OpenOffice. Les valeurs de filtre utilisees sont 
finalement reportees dans la feuille Options Filtre. Nous avons utilise cette macro 
pour trouver le codage des jeux de caracteres du tableau 7-17. 



Le terme technique Local e designe la langue employee pour un document ou un ele- 
ment du document (paragraphe, caractere, etc). Pour definir un Locale, l'API utilise 
une structure com. sun. star. lang. Locale composee de trois elements detailles au 
tableau 7-20. Les deux premiers sont utilises, par exemple, pour distinguer le francais 
parle en France ( fr-FR) du francais parle au Canada (fr-CA). 



Les informations du document 



La notion de Locale dans OpenOffice.org 



Tableau 7-20 Structure Locale 



Propriete 

Language 




Signification 



Stri ng 



Code de langue ISO 639, sous forme de deux lettres en 
minuscules, exemple : fr. 

Voir I'article http://fr.wikipedia.org/wiki/ISO_639 



Country 



Stri ng 



Code de pays ISO 31 66, sous forme de deux lettres en 

majuscules, exemple : FR. 

Voir I'article http://fr.wikipedia.org/wiki/ 

ISO_3166 



Vari ant 



Stri ng 



Variante specifique de certains logiciels ou vendeurs. 
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Les proprietes du document 

L'objet document (Writer, Calc, Draw, Impress) expose quelques proprietes interes- 
santes, voir le tableau 7-21 : 

Tableau 7-21 Informations sur le document 



Location 


String 


Adresse URL du fichier document. ChaTne vide s'il n'est pas encore 
sauvegarde. 


URL 


Stri ng 


Comme la propriete Location. 


CharLocale 


Object 


La langue utilisee par defaut dans le document, voir le tableau 7-20. 


NumberFormats 


Object 


Les formats de nombre disponibles dans le document, voir plus loin la 
section «Les formats de nombre». 


ApplyFormDesignMode 


Boolean 


True si le mode de conception de formulaire est active au charge- 
ment du document. 


RecordChanges 


Boolean 


Menu Edition>Modifications>Enregistrer 

True si les modifications de document sont enregistrees. 


Show/Changes 


Boolean 


Menu Edition>Modifications>Afficher 

True si les modifications de document sont affichees. 


Al 1 owMacroExecution 


Bool ean 


True si les macros du document peuvent s'executer. 


BasicLibraries 


Object 


Acces au conteneur des bibliotheques de codage Basic. 


DialogLibraries 


Object 


Acces au conteneur des bibliotheques de dialogue. 


Documentlnfo 


Object 


Informations diverses. Obsolete en version 3, voir ci-dessous. 


Document Properties 


Object 


Informations diverses. Introduit par la version 3, voir ci-dessous. 



Tout document bureautique OpenOffice.org contient des informations concernant le 
contexte dans lequel il a ete redige, comme son auteur ou sa date de creation. II s'agit 
des informations accessibles dans l'interface utilisateur par le menu Fichier>Proprietes. 
On les retrouve dans la propriete Documentlnfo et la propriete DocumentProperties. 
La premiere n'est plus utilisee avec la version 3, la deuxieme reprend ses informations 
et en ajoute d'autres. 



DocumentProperties 

La propriete DocumentProperties renvoie un objet dont le tableau 7-22 liste les 
principales proprietes (la plupart sont techniquement des attributs d'interface). 
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Tableau 7-22 Proprietes de DocumentProperties 



Element 


Type 


Signification 


Author 


Stri ng 


Auteur initial du document. 


CreationDate 


Object 


Date de creation du document, voir exemple. 


Description 


Stri ng 


Champ Commentaire des proprietes du document ; peut comporter 
plusieurs lignes. 


Keywords 


Stri ng 


Mots-cles. 


Language 


Object 


La langue utilisee par defaut dans le document, voir le tableau 7-20. 


Modi f i edBy 


Stri ng 


Norn du dernier utilisateur ayant enregistre le document. 


ModifyDate 


Object 


Date de derniere modification. 


Generator 


Stri ng 


La version precise du programme ayant ecrit ce document ; utile en cas 
d'anomalie. 


PrintedBy 


Stri ng 


Norn du dernier utilisateur ayant imprime le document. 


PrintDate 


Object 


Date de derniere impression. 


Subject 


Stri ng 


Champ Sujet des proprietes du document. 


Tempi ateName 


Stri ng 


Norn du modele utilise. 


Tempi ateURL 


Stri ng 


Chemin et nom du fichier modele utilise. 


Tempi ateDate 


Object 


Date du modele utilise. 


Title 


Stri ng 


Titre du document. 


EditingCycles 


Integer 


Numero de version. 


Editi ngDuration 


Long 


Duree d'edition, en secondes. 


DocumentStati sti cs 


Object 


Statistiques du document, voir ci-dessous. 


UserDefi nedProperti es 


Object 


Champs definis par I'utilisateur, voir ci-dessous. 



Les champs de date sont des structures com. sun. star. util .DateTime dont les ele- 
ments sont decrits au tableau 7-23. Un champ de date « vide » a ses elements a zero, 
en particulier Month et Day. 

Tableau 7-23 Structure DateTime 



Year 


Integer 


Annee, exemple de valeur : 1 987. 


Month 


Integer 


Mois de I'annee, valeur de 1 a 12. 


Day 


Integer 


Jour du mois, valeur de 1 a 31 . 


Hours 


Integer 


Heure de la journee, valeur de 0 a 23. 


Mi nutes 


Integer 


Minutes dans I'heure, valeur de 0 a 59. 


Seconds 


Integer 


Secondes dans la minute, valeur de 0 a 59. 


HundredthSeconds 


Integer 


Centiemes de seconde dans la seconde, valeur de 0 a 99. 
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Ainsi, voici comment recuperer et afficher des valeurs de date : 

rem Code07-01.odt bibli : DocProperti es Modulel 
Option Explicit 

Sub DatesDuDocumentO 

Dim monDocument As Object, doclnfos As Object, uneDate As Object 

monDocument = Thi sComponent 

doclnfos = monDocument . DocumentProperties 

uneDate = doclnfos . CreationDate 

MsgBox(DateTimeVersBasicDate(uneDate) , 0, "Date de creation") 
uneDate = doclnfos. Modi ficationDate 

MsgBox(DateTimeVersBasicDate(uneDate) , 0, "Date de modification") 
End Sub 



Function DateTimeVersBasicDate(dateTi me As Object) As Date 
With dateTime 

if (.Month = 0) or (.Day = 0) then ' date vide 
DateTimeVersBasi cDate = 0 

el se 

DateTimeVersBasi cDate = DateSe rial (.Year, .Month, .Day) _ 
+TimeSe rial (.Hours, .Minutes, .Seconds) 
end if 

I End With 
End Function 

Nous avons cree une fonction utilitaire pour convertir la valeur d'une structure 
DateTime en valeur de type Date pour Basic. Les instructions With. . . End With 
nous evitent de repeter la variable uneDate devant chaque element de la structure, 
mais le point doit cependant etre ecrit. La fonction Basic DateSerial renvoie la 
valeur de date (implementee en valeur entiere), la fonction Basic TimeSerial renvoie 
la valeur d'heure (implementee en fraction d'unite), et la somme des deux nous 
donne la valeur de date-heure. 

Vous pouvez modifier a volonte chacune des informations, exemple : 

rem Code07-01 . odt bibli : DocProperti es Module2 
Option Explicit 

Sub ChangerPropsDocO 

Dim monDocument As Object, doclnfos As Object 

monDocument = Thi sComponent 

doclnfos = monDocument . DocumentProperties 
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With doclnfos 
.Author = "Zoe" 

.Description = "comment changer les informations de document" 

.ModifiedBy = "Laura" 

.Title = "Essai de macro" 

.EditingCycles = 456 
End With 
End Sub 

La propriete DocumentStati sties renvoie un tableau de structures 
com. sun. star, beans. NamedValue, tres similaire a la structure PropertyVal ue. Chaque 
structure du tableau correspond a un compteur statistique, de type Long. Le nombre 
d'elements disponibles depend du type de document (Writer, Calc, Draw, etc). Seul 
Writer fournit des statistiques interessantes, mais le chapitre 8, section « Les informa- 
tions du document », indique comment en obtenir davantage, et plus facilement. 

Les champs definis par I'utilisateur 

Un document peut comporter des champs memorises pour un usage quelconque ; 
par exemple une information qui sera lue et modifiee par une macro. Auparavant, un 
document contenait par defaut les champs Info 1 a Info 4, de type texte. A partir 
de la version 3.1, I'utilisateur peut creer des champs, afficher et modifier leur contenu 
avec l'onglet Proprietes personalisees du panneau Fichier>Proprietes (figure 7-1). 
Chaque champ utilisateur peut memoriser une information de type texte, nombre, 
valeur booleenne, ou date. 
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En programmation, l'objet obtenu par la propriete UserDefi nedProperti es nous 
permet de lire ces champs utilisateur, en ajouter, en supprimer, ou modifier leur con- 
tenu. C'est ce que nous allons demontrer dans une macro qu'il est interessant de 
lancer plusieurs fois. 

rem Code07-01.odt bibli : DocProperti es Module3 
Option Explicit 

Sub gererLesChampsUtilisateur() 

Dim monDocument As Object, lesChamps As Object, n As Double 
monDocument = Thi sComponent 

1 esChamps = monDocument . DocumentProperti es . UserDefi nedProperti es 
listerChampsUtilisateur(lesChamps, "Etat initial") 

if not 1 esChamps . PropertySetlnfo. hasPropertyByName("UnTexte") then 
1 esChamps . addProperty("UnTexte" , 

com . sun . star . beans . PropertyAttri bute . REMOVEABLE , "bl abl a") 

listerChampsUtilisateur(lesChamps, "Apres creation du champ UnTexte") 
end if 

if not lesChamps. PropertySetlnfo. hasPropertyByName("UnNombre") then 
lesChamps.addProperty("UnNombre" , _ 

com . sun . star . beans . PropertyAttri bute . REMOVEABLE , _ 
CreateUnoValue("double", 0)) 
listerChampsUtilisateur(lesChamps, "Apres creation du champ UnNombre") 
end if 

if not lesChamps. PropertySetlnfo. hasPropertyByName("UnBi nai re") then 

lesChamps .addProperty("UnBi nai re" , _ 

com . sun . star . beans . PropertyAttri bute . REMOVEABLE , Fal se) 

listerChampsUtilisateur(lesChamps, "Apres creation du champ 
UnBinai re") 
end if 

if not 1 esChamps . PropertySetlnfo . hasPropertyByName("UneDate") then 
1 esChamps . addProperty ("UneDate" , _ 

com . sun . star . beans . PropertyAttri bute . REMOVEABLE , _ 

BasicDateVersDateTime(NowO) ) 
listerChampsUtilisateur(lesChamps, "Apres creation du champ UneDate") 
end if 

1 esChamps . setPropertyVal ue("UnTexte" , "Ceci est ecrit le " & Now()) 

n = lesChamps .getPropertyValue("UnNombre") 

1 esChamps . setPropertyVal ue("UnNombre" , n + 32.01) 

lesChamps . setPropertyVal ue("UneDate" , BasicDateVersDateTime(NowO) ) 
lesChamps. setPropertyVal ue("UnBi nai re" , True) 

listerChampsUtilisateur(lesChamps, "Apres modification des champs") 
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Ef facer ("UnTexte" , 1 esChamps) 
Effacer("UneDate" , 1 esChamps) 
Effacer("UnBi nai re" , lesChamps) 
Effacer("UnNombre" , lesChamps) 

listerChampslltilisateur(lesChamps, "Etat final") 
End Sub 



Sub Ef facer (nomChamp As String, 1 esChamps As Object) 

if 1 esChamps. PropertySetlnfo . hasPropertyByName(nomChamp) then 

if MsgBox("Effacer le champ " & nomChamp & " ?", 4) = 6 then 
1 esChamps . removeProperty (nomChamp) 

end if 
end if 
End Sub 



Function BasicDateVersDateTime(BasDate As Date) As Object 
Dim laDate As New com. sun. star. uti 1 .DateTime 

laDate.Year = Year(BasDate) : laDate. Month = Month(BasDate) 

laDate. Day = Day(BasDate) : laDate. Hours = Hour(BasDate) 

laDate. Minutes = Mi nute(BasDate) : 1 aDate . Seconds = Second (BasDate) 
Basi cDateVersDateTime = laDate 
End Function 



Sub listerChampsUtilisateur(lesChamps As Object, titre As String) 
Dim liste As String, lesProps As Variant, prop As Object 

lesProps = 1 esChamps. PropertyVal ues 

liste = "" 

For Each prop in lesProps 

if IsUnoStruct(prop. Value) then 

liste = liste & prop. Name &"="&_ 

DateTimeVersBasicDate(prop. Value) & chr(13) 

el se 

liste = liste & prop. Name & " = " & prop. Value & chr(13) 
end if 
next 

MsgBox(liste, 0, titre) 
End Sub 

Nous avons defini la routine listerChampsUtilisateur pour afficher chacun des 
champs du document. La routine est utilisee une premiere fois pour afficher l'etat 
initial des champs, puis apres chaque modification. A partir de l'objet 1 esChamps 
transmis en argument, elle obtient de sa propriete PropertyVal ues un tableau de 
structures com. sun. star. beans. PropertyVal ue. La boucle For Each explore ce 
tableau et ajoute dans une chaine de caracteres le nom et la valeur de chaque struc- 



Manipuler les documents OpenOffice.org 

Troisieme partie 



ture. Un champ utilisateur contenant une date est une structure UNO DateTime (voir 
le tableau 7-23). La fonction Basic IsUnoStruct renvoie True si la valeur de la pro- 
priete est une structure UNO, ce qui est le cas pour un champ date. On utilise alors 
la fonction DateTimeVersBasi cDate vue precedemment afin d'obtenir la date sous 
forme de chaine de caracteres. 

Avant d'ajouter un champ, on verifie qu'il n'existe pas deja, avec la methode 
hasPropertyByName de l'objet obtenu par PropertySetlnfo. Si elle renvoie False 
alors on cree ce champ par la methode addProperty qui emploie trois arguments : 
Arg 1 le nom du champ ; 

Arg 2 la valeur resultant de la somme de constantes de la serie 
com. sun . star . beans . PropertyAttri bute. Dans notre cas nous utiliserons seule- 
ment la constante REMOVEABLE qui declare que le champ peut etre supprime. Si 
nous avions mis a la place la valeur zero, le champ ne pourrait plus etre supprime. 

Arg 3 la valeur initiale du champ, soit une chaine, soit un nombre, soit une struc- 
ture DateTime. 

La valeur initiale du champ ne pose pas de probleme pour une chaine de caracteres, 
ni pour un boolean, ni pour une structure DateTime, car le type UNO est alors par- 
faitement defini. Mais le type exact d'un nombre doit etre precise (par exemple 
doubl e ou 1 ong) car il y a en general ambiguite. Pour cela, on utilise la fonction Basic 
CreateUnoVal ue, decrite a 1' annexe A. Son premier argument est le nom du type 
UNO a utiliser (respecter la casse), le deuxieme argument contient la valeur a mettre. 

La fonction Basic Now renvoie la date-heure actuelle, dans le type Basic Date. Nous 
avons defini la fonction BasicDateVersDateTime pour obtenir une structure 
DateTime initialisee a une date-heure exprimee dans le type Basic Date. On utilise 
pour cela diverses fonctions offertes par Basic, que nous avons vues au chapitre 5. Le 
caractere « deux points » permet de mettre plusieurs instructions sur la meme ligne. 

Pour modifier la valeur d'un champ, on doit utiliser la methode setPropertyVal ue 
(les langages de Script comme Basic ne savent pas reconnaitre des proprietes creees 
dynamiquement). Le premier argument est le nom du champ (respecter la casse), le 
deuxieme est la nouvelle valeur. Symetriquement, la methode getPropertyVal ue 
renvoie la valeur actuelle d'un champ. 

Enfin, la methode removeProperty supprime un champ, a condition qu'il ait ete 
defini comme REMOVEABLE. Nous 1' avons employee dans la routine Effacer, afin de 
supprimer chaque champ apres autorisation. Si vous en gardez quelques-uns, un 
deuxieme lancement de la macro montrera que les champs sont bien memorises. 
Toutefois l'etat « modifie » du document n'est pas change ! Pour memoriser les chan- 
gements, vous devrez soit imposer l'etat « modifie », soit sauver le document par pro- 
gramme, comme indique dans ce chapitre, section « Sauver le document ». 
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Comment le document a-t-il ete charge ? 

LorsquOpenOffice.org charge un document, il choisit certaines options. En char- 
geant un document par programme, nous pouvons imposer certaines options. Tout 
document charge, meme nouveau, memorise des options de chargement dans la 
pseudo-propriete Args. Elle contient un tableau de PropertyVal ue dont certains ele- 
ments sont des proprietes du service com. sun. star. document. MediaDescriptor que 
nous avons vues precedemment pour la sauvegarde. Si le document est sauvegarde 
sous un autre nom ou un autre format par saveAsURL la liste des proprietes de Args 
est mise a jour. 

Important a savoir, sur la liste des proprietes de Args : 

• Elle contient des proprietes non documentees. 

• Certaines proprietes happaraissent que lorsque la valeur n'est pas celle par defaut, 
par exemple Readonly. 

• Une sauvegarde peut changer le nombre et l'ordre des proprietes dans la liste. 

Utilisez les routines utilitaires hasPropO et getPropVal () decrites a l'annexe B pour 
acceder aux proprietes. Ici nous avons charge un document et desirons visualiser le 
filtre qu'a employe OpenOffice.org : 

Dim p As String 

if hasProp(monDocument . Args , "Fi 1 terName") then 

p = getPropVal (monDocument.Args, "FilterName") 

print p 
end if 

Le tableau 7-24 indique quelques particularites. Les valeurs possibles sont celles 
decrites au tableau 7-2. 

Tableau 7-24 Proprietes de document.Args 





Type 


Remarque 


URL 


Stri ng 


L'adresse du document, ou du modele si le document n'a pas encore 
ete sauve. 


AsTemplate 


Boolean 


Distingue si c'est le document issu du modele, ou le modele lui-meme 
qui est charge. Voir les explications deja donnees sur cette propriete. 


Fi "IterName 


Stri ng 


Nom du filtre ayant servi a charger le document, ou ayant servi a 

creer le nouveau document a partir du modele. 

Si le document est ensuite converti en un autre format, 

Fi 1 te rName est mis a jour. 


MacroExecuti onMode 


Integer 


Precise les conditions d'execution des macros du document. 


UpdateDocMode 


Integer 


Precise les conditions de mise a jour des liens exernes du document 
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Les formats de nombre 

Differents formats de nombre sont disponibles par defaut dans chaque document 
Writer ou Calc (mais pas Draw ni Impress). L'utilisateur peut en ajouter d'autres, qui 
ne seront connus que dans le document. La collection des formats disponibles est 
geree par l'objet NumberFormats, contenu dans l'objet document. Chaque format est 
accessible par une cle, qui est une simple valeur numerique (un index). La difficulte 
est de trouver la cle, ce que nous expliquerons plus loin. Le tableau 7-25 liste les pro- 
prietes d'un format. 

Tableau 7-25 Proprietes d'un format numerique 



Propriete 




Signification 


FormatStri ng 


Stri ng 


Le format exprime sous forme d'une chame de caracteres. 


Locale 


Object 


Langue utilisee pour ce format. Voir le tableau 7-20. 


Type 


Integer 


Type de format de nombre, voir le tableau 7-26. 


Comment 


Stri ng 


Commentaire sur le format, pour l'utilisateur. 



La valeur de Type d'un format est une constante nommee (tableau 7-26) de la forme : 
| com. sun. star. util .Number Format. CURRENCY 

Tableau 7-26 Constantes de type de format numerique 



DEFINED 


Defini par l'utilisateur. 


DATE 


Date. 


TIME 


Heure. 


DATETIME 


Date et heure. 


CURRENCY 


Monetaire. 


NUMBER 


Nombre decimal. 


SCIENTIFIC 


Nombre au format flottant. 


FRACTION 


Nombre fractionnaire. 


PERCENT 


Pourcentage. 


TEXT 


Texte. 


LOGICAL 


Valeur booleenne. 



La cle d'acces a un format est utilisee dans de nombreuses proprietes nominees 
NumberFormat, pour des champs de texte, pour des cellules de tableau. 
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L'ensemble des cles existantes pour un ou plusieurs types de format est renvoye par la 
methode queryKeys de l'objet collection des formats. On ne peut connaitre que les 
cles correspondant a une valeur donnee de Local e, car OpenOffice.org cree les cles 
selon les caracteristiques propres a un couple langue-pays (separateur decimal, sepa- 
rateur de milliers, symbole monetaire, etc.). La methode getByKey renvoie la chaine 
de caracteres pour le formatage, correspondant a une cle. 

Le document Code07-07.ods du Zip telechargeable contientla macro ListerFormats 
qui affiche dans une feuille de tableur la liste des formats disponibles pour une valeur 
de Local e. Nous ne detaillerons pas cette macro. II vous suffira de cliquer sur le bouton 
situe sur la premiere feuille. La macro vous demandera la langue, puis la variante de 
pays pour le Local e. Faites des essais avec diverses valeurs, par exemple : ri en , ri en ; 
fr, Men ; fr, FR ; fr, LU ; en, GB ; en, US ; es ; de. Vous constaterez que : 

• Les valeurs de cles dependent du Local e et il y a des trous dans la numerotation. 

• Le nombre de cles disponibles depend du Local e. 

• La chaine de caracteres FormatString depend aussi du Locale. 

• Quand on ne precise pas de valeur de langue et pays pour le Local e, l'API utilise 
la valeur indiquee pour Environnement linguistique dans le panneau du menu 
Outils>Options>Parametres linguistiques>Langues. 

• Les formats definis par l'utilisateur sont ajoutes en fin de liste pour un Locale 
donne (nous avons defini un format pour le Locale rien, rien et un format 
pour le Locale fr, LU). 

Conclusion : il est risque d'affecter a une cellule une cle de format si on ne peut etre 
sur du document sur lequel on travaille. II faut done rechercher si ce format existe. 

Attention 

Meme une cle de format disponible par defaut peut dependre de la version OpenOffice.org avec laquelle 
le document a ete cree. 

On obtient la cle correspondant a une chaine de format pour un Local e donne avec 
la methode queryKey (notez le singulier). S'il n'y a pas de cle, la methode renvoie une 
valeur negative. On peut alors demander a creer une nouvelle cle avec la methode 
addNew. On utilise alors la cle ; si le besoin etait temporaire, on peut ensuite sup- 
primer la cle avec la methode removeByKey. Le codage suivant illustre ces etapes. 

rem Code07-07 . ods bibli : FormatNombres Module2 
Option Explicit 
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Sub AjouterSupprimerUneCleO 
Dim monDocument As Object 

Dim laCle As Long, monFormat As String, lesFormats As Object 
Dim patois As New com . sun . star . 1 ang . Local e 
monDocument = thi sComponent 

patoi s . Language = InputBox("Langue (rien, fr, es , de...)") 

patois. Country = InputBox("Vari ante de pays (rien, FR, ES, DE, LU...)") 

monFormat = InputBox("Chai ne de format recherchee") 

lesFormats = monDocument . NumberFormats 

laCle = 1 esFormats . queryKey(monFormat , patois, false) 

if laCle < 0 then 

MsgBox("Pas de cle pour ce format, creation d'une cle") 

laCle = lesFormats .addNew (monFormat, patois) 

MsgBox("Nouvelle cle : " & laCle) 

MsgBox("Ce format va etre supprime") 
1 esFormats . removeByKey (1 aCl e) 
el se 

MsgBox("Cle : " & laCle) 
end if 
End Sub 

Le troisieme argument de queryKey n'est pas utilise actuellement ; il doit etre mis a 
False. Une erreur est declenchee si vous tentez d'ajouter un format existant pour le 
Local e, d'ou la necessite de tester s'il existe. 

Une fois en possession de votre cle, formater une cellule ou une zone dans Calc ou 
dans un tableau Writer est un jeu d'enfant : 

maCellule.NumberFormat = laCle 
maZone . Number-Format = laCle 

D'autres objets de l'API comportent une propriete NumberFormat, qu'on exploite de 
la meme maniere. 

Le service NumberFormatter vous permet, a partir d'un nombre Doubl e d'obtenir une 
chaine de caracteres correspondant au format de la cle ou, inversement, d'analyser 
une chaine formatee selon la cle pour obtenir le nombre Doubl e correspondant. 

rem Code07-07 . ods bibli : FormatNombres Module3 
Option Explicit 

Sub FormaterNombre 

Dim monDocument As Object, sv As Object 

Dim unNombre As Double, nombreAff i che As String, laCle As Long 
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monDocument = Thi sComponent 

sv = CreateUnoService("com. sun. star. util .Number-Formatter") 
sv.attachNumberFormatsSuppl ier (monDocument) 

laCle = 5 ' format (dans ce document) : # ###,00 
unNombre = 123456.7892 ' formater ce nombre selon la cle 
nombreAf fi che = sv.convertNumberToString(laCle, unNombre) 
MsgBox(nombreAff i che) 

laCle = 11 ' format (dans ce document) : 0,00% 
nombreAff i che = "-13,1%" ' decoder le nombre correspondant 
unNombre = sv . convertStringToNumber (1 aCl e , nombreAff i che) 
MsgBox (unNombre) 
End Sub 

Les mecanismes de format numerique sont tres riches et complexes. Pour aller plus 
loin, consultez le Developer's Guide, section Office Development>Common Application 
Features>Number Formats. 



Les evenements du document 

Depuis le menu Outils>Personnaliser, vous pouvez affecter une macro a un evenement 
concernant un document particulier (si l'affectation est faite sur ce document) ou 
concernant tout document OpenOffice, si l'affectation est faite sur OpenOffice.org. 
Depuis la version OpenOffice.org 3.1, on peut recuperer un argument donnant quel- 
ques informations complementaires. Attention, avant la version 3.1 aucun argument 
n'est transmis. Dans un document, on aura un codage ressemblant a : 

Sub traiterEvenement( Optional evt as object) 

if IsMi ssi ng(evt) then 

' la version OOo est trop ancienne, aucune information disponible 
el se 

1 utiliser les informations liees a 1 'evenement 

MsgBox (evt . EventName , 0, "Norn de 1 ' evenement") 
end if 
End Sub 

Le tableau 7-27 presente les proprietes de l'objet transmis avec 1' evenement. 
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Tableau 7-27 Proprietes d'evenement de document 



EventName 


Stri ng 


Nom de I'evenement. 


Source 


Object 


L'objet document a I'origine de I'evenement. 


Vi ewControl 1 er 


Object 


Controleur d'affichage conceme par I'evenement, ou valeur Nul 1 . 


Supplement 


Variant 


Information complementaire propre a I'evenement, ou valeur Empty. 



Les styles 

Les documents OpenOffice.org comportent des styles. II est de loin preferable de 
definir vos styles avec le panneau Styles et formatage dans un document qui vous ser- 
vira de modele. Malgre tout, vous pouvez avoir a faire quelques modifications d'un 
style existant ; c'est ce que nous allons essentiellement decrire. 

L'archive Zip telechargeable contient des exemples de codages similaires pour Writer, 
Calc et Draw, dans les fichiers Code07-ll . odt, Code07-12 . ods, Code07-13 . odg. 

Trouver les styles 

Les styles sont regroupes en famille, par exemple la famille des styles de paragraphe. 
Dans chaque famille, on trouve une collection de styles. 

La macro suivante liste tous les styles d'un document Writer. Comme cette liste est 
assez longue, nous allons l'ecrire dans le document lui-meme, ce qui nous fera un 
bon exercice d'ecriture par macros. 

rem Code07-ll.odt bibli : Modi f Styles Modulel 
Option Explicit 

Sub ListerStylesO 

Dim monDocument As Object 

Dim monTexte As Object, monCurseur As Object 

Dim lesFamilles As Object, uneFamille As Object 

Dim styleX As Object, liste As String, nomFam As String 

Dim f As Long, x As Long 

Dim sautPage As Integer, sautLigne As String 

sautPage = com . sun . star . text . ControlCharacter . PARAGRAPH_BREAK 

sautLigne = chr(10) 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

monCurseur = monTexte. createTextCursor 

monCurseur. gotoEnd(False) ' ajouter en fin de document 
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lesFamilles = monDocument . Styl eFamil ies 

for f = 0 to lesFamilles. Count -1' chaque f ami lie 

nomFam = lesFamilles.ElementNames(f) 

uneFamille = lesFamilles. getByName(nomFam) 

liste = "*** Famille " & nomFam 
for x = 0 to uneFamille. Count -1' chaque style 
styleX = uneFamille(x) 

liste = liste & sautLigne & chr(9) & styleX.Name _ 

& " = " & styleX.DisplayName 

next x 

monTexte.insertString(monCurseur, liste, false) 

monTexte . i nsertControl Character(monCurseur , sautPage , fal se) 

next f 

End Sub 

La propriete Styl eFami 1 i es de l'objet document donne acces a toutes les families de 
styles, qui existent dans le document : c'est un objet conteneur. Le nombre de 
families est la propriete Count de l'objet lesFamilles ; la liste des noms de families 
est disponible dans le tableau ElementNames de ce meme objet. Le tableau 7-28 
indique les families de styles selon le type de document. 

Tableau 7-28 Noms des families de styles 



Calc Draw Impress 



CharacterStyles 


Cell Styles 


graphics 


graphics 


ParagraphStyles 


PageStyles 


cell 


cell 


FrameStyles 




table 


table 


PageStyles 








NumberingStyles 









On accede a une famille du conteneur soit par son nom avec la fonction getByName, 
soit par son numero d'ordre, avec la fonction getBylndex. Avec OOoBasic, le 
getBylndex peut etre omis, comme si on indexait une variable tableau. Lordre n'est 
pas forcement le meme que dans ElementNames. C'est pourquoi nous obtenons 
chaque famille en utilisant son nom. 

Chaque famille est elle aussi un conteneur. Le nombre de styles dans une famille est 
indique par sa propriete Count. On accede a un style par getByName ou getBylndex. 
Ici nous utilisons la pseudo-indexation de Basic. Le nom du style est obtenu avec sa 
propriete Name. Les styles predefinis en standard ont un nom interne anglais. La 
macro indique aussi le nom localise grace a la propriete Di spl ayName. 
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Recuperer ou supprimer un style du document 

Si vous connaissez le nom du style a modifier, et evidemment le nom de la famille, il 
sera facile de recuperer le style car les objets disposent d'un acces par le nom. Void 
comment on recupere le style de page « Standard » : 

Dim nomStyleMaPage As String, StyleMaPage As Object 
Dim lesStylesPage As Object 

1 esStyl esPage = monDocument . Styl eFami 1 i es . getByName("PageStyl es") 
StyleMaPage = 1 esStyl esPage . getByName(" Standard") 

Notez que getByName fonctionne pour un nom de style anglais ou localise. 
Pour tester si un style existe dans une famille, on utilise la fonction HasByName : 

-if lesStyl esPage. hasByName("HTML") then 

' f ai re un traitement 
end "if 

Pour supprimer un style personnel existant, on utilise la methode removeByName : 
1 esStyl esPage . removeByName("monStyl e") 



Recuperer des styles d'un autre document 

A defaut de creer votre document a partir d'un modele comportant les styles sou- 
haites (c'est la meilleure solution), vous pouvez copier dans votre document des styles 
existants dans un autre document. Ceci n'est possible que pour Writer et Calc. Cet 
exemple ne charge que les styles de page sans modifier les styles existants. 

rem Code07-ll.odt bibli : Modi f Styles Module2 
Option Explicit 

Sub ChargerStylesO 

Dim monDocument As Object, options As Variant, refDoc As String 

refDoc = convertToURL("C:\Docs OpenOf fi ce\mesStyl es . odt") 
monDocument = Thi sComponent 

options = monDocument . Styl eFami 1 i es .getStyl eLoaderOptions 
setPropVal (opti ons , "LoadTextStyles" , False) 
setPropVal (opti ons , "LoadFrameStyl es" , False) 

setPropVal (opti ons , "LoadPageStyles" , True) ' ceci est inutile (defaut) 

setPropVal (options, "LoadNumberingStyl es" , False) 

setPropVal (options, "OverwriteStyles" , False) 

monDocument . Styl eFami 1 i es . 1 oadStyl esFromURL( refDoc , opti ons ()) 

End Sub 
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La methode getStyleLoaderOptions nous renvoie un tableau de PropertyVal ue 
contenant les options possibles. Elles sont listees au tableau 7-29, et toutes initiali- 
sers par defaut a True. Nous utilisons la routine utilitaire setPropVal, decrite a 
l'annexe B, pour modifier les valeurs de ces proprietes, afin de ne charger que les 
styles de page sans ecraser les styles de page existants. Le chargement des styles est 
realise par la methode loadStylesFromURL qui prend en argument l'adresse du docu- 
ment de reference, et le tableau d'options. 

Tableau 7-29 Proprietes d'options de chargement de style 



Document Propriete Type Signification pour la valeur True 



Writer 


LoadTextStyles 


Boolean 


Charger les styles de paragraphe et de caractere. 


Writer, Calc 


LoadPageStyles 


Boolean 


Charger les styles de page. 


Writer 


LoadFrameStyles 


Boolean 


Charger les styles de cadre. 


Writer 


LoadNumberi ngStyl es 


Boolean 


Charger les styles de numerotation (styles de liste, dans 
I'interface utilisateur version francaise). 


Calc 


LoadCell Styles 


Boolean 


Charger les styles de cellule. 


Writer, Calc 


Overwri teStyl es 


Boolean 


Ecraser les styles existants lors du chargement. 



Creer un nouveau style 

La macro ci-dessous cree un nouveau style de paragraphe a partir d'un style existant, 
et le modifie avant de l'inserer dans la famille ParagraphStyles. Dans le panneau 
Styles et formatage, basculez eventuellement i'affichage d'une famille de styles a l'autre 
pour faire apparaitre le nouveau style. 

rem Code07-ll . odt bibli : Modi f Styles Module3 
Option Explicit 

Sub CreerStyle() 

Dim monDocument As Object 

Dim lesFamilles As Object, uneFamille As Object, nouvStyle As Object 

monDocument = ThisComponent 

lesFamilles = monDocument. StyleFami lies 

uneFamille = lesFamilles. getByName("ParagraphStyl es") 

nouvStyl e = monDocument . createInstance("com . sun . star . styl e . ParagraphStyl e") 
uneFamille. insertByName ("Signature coloree", nouvStyle) 
nouvStyl e.ParentStyle = "Signature"' heriter d'un style 
nouvStyle. CharColor = RGB(0,100,255) ' changer la couleur 
End Sub 

Lheritage d'un style avec la propriete ParentStyle ne fonctionne pas pour les styles 
de page et de numerotation car ils ne sont pas hierarchises. On obtient alors un style 
conforme au style Standard, qu'il faudra adapter a ses besoins. 
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Modifier un style 

Un style possede diverses proprieties servant a formater le document. Une fois un 
style recupere, il suffit de modifier la valeur des proprietes souhaitees. Dans 
l'exemple precedent de creation d'un nouveau style nous avons ainsi change la cou- 
leur de caractere utilisee dans un style de paragraphe. Les proprietes de formatage 
sont decrites dans les chapitres consacres a Writer, Calc, Draw/Impress. 

Les proprietes communes des styles 

La methode isInUse renvoie la valeur True si ce style, ou un style derive, est effecti- 
vement utilise dans le document. 

La methode i sUserDef i ned renvoie la valeur True si ce style a ete cree par l'utilisateur. 
Le tableau 7-30 liste des proprietes communes aux differentes families de styles. 
Tableau 7-30 Proprietes communes des styles 





Type 




ParentStyle 


String 


Norn du style parent. 


Name 


Stri ng 


Norn interne du style. 


DisplayName 


String 


En lecture seule. Norn localise du style, pour I'interface utilisateur. 



Les proprietes et particularites propres a chaque famille de styles sont decrites dans 
les chapitres consacres aux types de documents Writer, Calc et Draw/Impress. Le 
domaine etant vaste, etudiez la documentation de l'API pour aller plus loin, a partir 
des liens de la page com . sun . star . sty! e. 



Configuration d'affichage d'un document 

Chaque type de document possede des proprietes d'affichage accessibles a partir de 
l'objet controleur du document. La maniere d'y acceder peut varier, et les proprietes 
sont pour la plupart specifiques. 

Les proprietes du zoom d'affichage sont, elles, identiques. Elles sont au nombre de 
deux : 

• ZoomType, de type Integer, qui recoit une constante nommee de la forme 
com. sun. star. view.DocumentZoomType. OPTIMAL et dont les valeurs possibles 
sont listees dans le tableau 7-31 ; 

• ZoomValue, de type Integer, qui recoit le facteur de zoom en pourcentage. Cette 
propriete est utilisee quand ZoomType vaut BY_VALUE. 
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Tableau 7-31 Constantes de facteur de zoom 



instante 



OPTIMAL 


Optimal. 


PAGE_WIDTH 


Largeur de page. 


ENTIRE_PACE 


Page entiere. 


PAGE_WIDTH_EXACT 


Page entiere. 


BY_VALUE 


Facteur de zoom selon ZoomVal ue. 



Exemple, sur un document Writer : 

rem Code07-01 . odt bibli : Config Modulel 
Option Explicit 



Sub ZoomerO 

Dim monDocument As Object, conf As Object 
Dim z As Integer 
monDocument = thi sComponent 

conf = monDocument. CurrentController .ViewSettings 

z = InputBox("Facteur de zoom, en %, ou zero") 
if z > 0 then 

conf .ZoomVal ue = z 

conf .ZoomType = com. sun . star . vi ew. DocumentZoomType . BY_VALUE 
el se 

conf .ZoomType = com. sun. star. view. DocumentZoomType. PAGE_WIDTH 
end if 
End Sub 



Configuration d'un document 

Le service DocumentSetti ngs de chaque type de document fournit quelques infor- 
mations interessantes. Pour les obtenir, nous devons invoquer le service a partir de 
l'objet document, par exemple pour un document Writer : 

rem Code07-01 . odt bibli : Imprimer Module3 
Option Explicit 

Sub ConfiglmpressionO 

Dim monDocument As Object, conf As Object, servConfig As String 
monDocument = Thi sComponent 

servConfig = "com. sun. star. text. DocumentSetti ngs" 

conf = monDocument. createlnstance(servConfig) 
print conf . PrinterName 

End Sub 
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Le nom du service depend du document, voyez le tableau 7-32. 



Tableau 7-32 Service de configuration de document 





Writer 


com . sun . star . text . DocumentSetti ngs 


Calc 


com. sun . star . comp . SpreadsheetSetti ngs 


Draw 


com. sun .star . drawi ng . DocumentSetti ngs 


Impress 


com . sun . star . presentati on . DocumentSetti ngs 



Quelques proprietes communes sont listees au tableau 7-33. Nous signalons dans les 
chapitres consacres a chaque type de document les proprietes de configuration qui 
leur sont specifiques et particulierement notables. 



Tableau 7-33 Proprietes communes de configuration 



Propriete 


Type 


Signification 


Pri nterName 


Stri ng 


Nom de I'imprimante utilisee par le document. 


SaveVersionOnClose 


Boolean 


True pour creer une nouvelle version a la fermeture du document modifie. 


UpdateFromTempl ate 


Boolean 


True pour mettre a jour le document si son modele a evolue. 


FieldAutoUpdate 


Boolean 


True pour que les champs soient mis a jour automatiquement. 



Conclusion 

Le premier chapitre de cette partie a ete l'occasion d'utiliser l'API d'OpenOffice.org 
pour manipuler les documents. Ouverture, fermeture, impression, import/export... 
nous avons agi independamment de leur nature. 

Le chapitre suivant expose et illustre l'API propre aux documents issus du traitement 
de texte Writer. 
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Dans ce chapitre, nous allons commencer par exposer les activites les plus courantes 
dans la manipulation par macro des documents Writer : lire et ecrire du texte dans le 
document, formater du texte, rechercher et remplacer du texte. Nous aborderons 
ensuite des domaines plus specialises comme les tableaux et les cadres, les styles, les 
signets. Vous retrouverez parfois exactement les memes concepts dans un contexte 
different. Ceci provient de la conception globale de l'interface de programmation 
(l'API) d'OpenOffice.org et vous facilitera l'apprentissage. 

API Reference sur Writer (en anglais) 

La documentation de l'API est decrite dans le Developer's Guide, au chapitre Text Documents. 

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ 

OpenOffice.org_Developers_Guide 



L'objet Text 

Pour travailler sur le texte d'un document Writer, nous avons besoin de preciser de 
quel texte il s'agit. En effet, un document Writer contient differents objets : le texte 
ordinaire, les en-tetes et pieds de page, ou des cadres contenant du texte. Le texte 
principal est l'objet Text, obtenu a partir du document : 

Dim monDocument As Object, monTexte As Object 
monDocument = Thi sComponent 
monTexte = monDocument .Text 
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La variable monTexte nous permet de manipuler l'objet Text du document. Elle pos- 
sede une propriete ayant pour nom String, qui represente l'ensemble des caracteres 
du texte. Cette propriete fournit une chaine de caracteres. Le codage suivant affiche 
les 1 000 premiers caracteres du texte du document Writer. 

rem Code08-01.odt bibli : Ecn'tureTexte Modulel 
Option Explicit 

Sub Affi cherTexteO 

Dim monDocument As Object, monTexte As Object 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

' afficher les premiers caracteres du texte 

MsgBox Left (monTexte. St ring, 1000) 

End Sub 

Inversement, en affectant une chaine de caracteres a la propriete String, nous chan- 
geons le texte entier du document : 

rem Code08-01.odt bibli : Ecn'tureTexte Module2 
Option Explicit 

Sub EcraserTexteO 

Dim monDocument As Object, monTexte As Object 
monDocument = Thi sComponent 
monTexte = monDocument. Text 

monTexte. St ring = "J'ai ecrase tout le texte !" 

End Sub 

Si vous avez execute cette macro, il ne vous reste plus qua cliquer sur le bouton 
d'annulation dans la fenetre du document, afin de recuperer l'ancien texte. 

Cette methode de lecture et d'ecriture est simple, mais tres limitative. D'une part, le 
texte manipule doit avoir moins de 65 536 caracteres pour qu'il soit contenu dans le 
type String. D'autre part, nous ne pouvons pas imposer un formatage particulier de 
certaines zones du texte. Pour avoir plus de possibilites, nous allons utiliser un objet 
curseur, qui permet de preciser la zone de texte que nous voulons lire ou modifier. 

Le curseur d'ecriture 

II faut bien comprendre qu'il existe deux types de curseurs : 

• le curseur visible, celui que vous voyez avancer quand vous tapez du texte dans 
Writer (il sera decrit plus loin) ; 

• le curseur d'ecriture, invisible, qui est utilise par la macro pour designer le texte 
quelle manipule. 
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La position courante d'un curseur d'ecriture n'est absolument pas liee a la position du 
curseur visible. 

On peut creer un ou plusieurs curseurs d'ecriture grace a la methode 
createTextCursor de l'objet Text du document. 

Dim monCurseur As Object 

monCurseur = monTexte. createTextCursor 

Le curseur peut, soit indiquer un point d'insertion dans le texte, soit delimiter une 
zone de selection dans le texte (comme un curseur visible). A la creation, le curseur 
est un point d'insertion place au debut du texte. II avancera en fonction des caracteres 
ecrits par la macro. Pour inserer du texte a un endroit quelconque du texte existant, il 
nous faut apprendre a deplacer ce curseur. 

L'objet curseur comporte un tres grand nombre de proprietes et de methodes. Grace 
a lui, il est possible d'obtenir des informations ou de modifier le caractere, le para- 
graphe et bien d'autres elements auxquels il est lie. 

Deplacer le curseur d'ecriture 

L'objet curseur dispose de plusieurs methodes permettant de le deplacer. Elles ont 
toutes un argument booleen, que nous designerons par SEL et qui a l'effet suivant : 

• SEL = False : le curseur se deplace (comme la barre verticale du curseur visible), 

• SEL = True : le curseur se deplace en etendant la selection (c'est le meme effet 
qu'une selection progressive du curseur visible en faisant glisser la souris). 

La plupart de ces methodes renvoient un resultat : 

• True si Taction a pu etre realisee, 

• Fal se dans le cas contraire. 

En pratique, on exploite rarement le resultat de ces fonctions. On les utilise comme 
des methodes de type sous-programme, comme dans ce petit exemple : 

Dim monDocument As Object, monTexte As Object 

Dim monCurseur As Object 

monDocument = Thi sComponent 

monTexte = monDocument .Text 

monCurseur = monTexte. createTextCursor 

' ici le curseur est au debut du texte 

' aller au paragraphe suivant 

monCurseur.gotoNextParagraph (False) 

' selectionner les 3 caracteres suivants 

monCurseur. goRight(3 .True) 
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Le tableau 8-1 liste les fonctions de emplacement de curseur. La methode gotoRange 
est un peu particuliere : elle utilise en premier argument une zone de texte (en 
anglais, TextRange), qui est un reperage dans le texte. Cette zone peut provenir de 
differents objets, en general un autre curseur ou une ancre (en anglais, Anchor). Nous 
donnerons un exemple un peu plus loin. 

Tableau 8-1 Deplacement du curseur d'ecriture 



goRight(n,SEL) 


Boolean 


Deplacer de n caracteres a droite. 


goLeft(n,SEL) 


Bool ean 


Deplacer de n caracteres a gauche. 


gotoStart(SEL) 


Aucun 


Deplacer au debut du texte entier. 


gotoEnd(SEL) 


Aucun 


Deplacer a la fin du texte entier. 


gotoRange (zone , SEL) 


Boolean 


Positionner le curseur sur une zone donnee. 


gotoStartOfParagraph(SEL) 


Boolean 


Deplacer au debut du paragraphe en cours. 


gotoEndOf Paragraph (SEL) 


Boolean 


Deplacer a la fin du paragraphe en cours. 


gotoNext Paragraph (SEL) 


Bool ean 


Deplacer au debut du paragraphe suivant. 


gotoPrevious Paragraph (SEL) 


Bool ean 


Deplacer au debut du paragraphe precedent. 


gotoNextWord(SEL) 


Boolean 


Deplacer au debut du mot suivant. 


gotoPrevi ousWord(SEL) 


Boolean 


Deplacer au debut du mot precedent. 


gotoStartOfWord(SEL) 


Boolean 


Deplacer au debut du mot courant. 


gotoEndOfWord(SEL) 


Boolean 


Deplacer a la fin du mot courant. 


gotoNextSentence(SEL) 


Bool ean 


Deplacer au debut de la phrase suivante. 


gotoPrevi ousSentence (SEL) 


Boolean 


Deplacer au debut de la phrase precedente. 


gotoStartOfSentence(SEL) 


Boolean 


Deplacer au debut de la phrase courante. 


gotoEndOf Sentence (SEL) 


Boolean 


Deplacer a la fin de la phrase courante. 



Le tableau 8-2 liste les fonctions de l'objet curseur qui indiquent si le curseur est a un 
endroit remarquable. Elles renvoient toutes True si la reponse est affirmative, Fal se 
dans le cas contraire. Ces fonctions n'utilisent pas d'argument, done les parentheses 
peuvent etre omises en Basic. 

| "if monCurseur . isEndOfWord then print "Fin de mot" 

Tableau 8-2 Fonctions testant si le curseur est a une position remarquable 







i sStartOf Paragraph() 


Boolean 


Le curseur est-il au debut d'un paragraphe ? 


isEndOf Paragraph () 


Boolean 


Le curseur est-il a la fin d'un paragraphe ? 
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Tableau 8-2 Fonctions testant si le curseur est a une position remarquable (suite) 



auction 



isStartOfWordO 


Bool ean 


Le curseur est-il au debut du mot en cours ? 


isEndOfWordO 


Boolean 


Le curseur est-il a la fin du mot en cours ? 


i sStartOfSentenceO 


Boolean 


Le curseur est-il en debut de phrase ? 


"i sEndOfSentence() 


Boolean 


Le curseur est-il en fin de phrase ? 


isCollapsedQ 


Boolean 


Le curseur est-il un simple point d'insertion ? 



Aller plus loin La notion de mot 

Les fonctions de deplacement et de test concernant les mots et les phrases peuvent donner des resultats 
surprenants. Writer considere qu'un mot se termine avec un espace, une fin de paragraphe, un retour 
force a la ligne, ou un des caracteres de la chame WordSeparator, qui est une propriete du docu- 
ment. De plus, le deplacement du curseur de mot s'arrete sur des caracteres comme « +/, ». 



La fonction isCollapsed merite une explication : elle renvoie False si le curseur est 
etendu pour une selection. Dans ce dernier cas, le curseur s'etend d'une position a 
une autre dans le texte. On peut revenir a un curseur ponctuel en utilisant une des 
deux methodes de l'objet curseur qui sont listees ci-dessous. Ces methodes n'ont pas 
d'argument. 

' redui re le curseur sur sa position de debut 
monCu rseu r . col 1 apseToStart 

' redui re le curseur sur sa position de fin 
monCu rseu r . col 1 apseToEnd 



Autres initialisations d'un curseur 

Dans certains cas, il est interessant d'utiliser un autre curseur d'ecriture qui soit ini- 
tialise aux valeurs du curseur actuel. On utilise pour cela la methode 
createTextCursorByRange de l'objet Text. Dans cet exemple, curseur2 reprend la 
position et la selection dans le texte memorisees par monCurseur : 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object, curseur2 As Object 
monDocument = Thi sComponent 
monTexte = monDocument .Text 
monCurseur = monTexte. createTextCursor 
monCu rseu r . gotoNextParag raph (Fal se) 
monCurseur .goRight (3 , True) 

curseur2 = monTexte. createTextCursorByRange(monCurseur) 
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Les objets curseur2 et monCurseur peuvent etre deplaces ou modifies independam- 
ment Fun de l'autre. 

On peut aussi creer un autre curseur a partir du premier en precisant qu'il doit se 
positionner a la fin de la zone de texte designee par monCurseur. II suffit de modifier 
la derniere ligne ainsi : 

curseur2 = monTexte . createTextCursorByRange(monCurseur . End) 

Pour creer curseur2 au debut de la zone de monCurseur on ecrirait : 
curseur2 = monTexte. createTextCursorByRange(monCurseur . Start) 

Nous pouvons aussi positionner un curseur existant sur une zone de texte, en 
employant la methode gotoRange du curseur, par exemple : 

curseur2 . gotoRange(monCurseur . End) 

Notez que les deux methodes createTextCursorByRange et gotoRange utilisent 
comme argument un objet zone de texte (en anglais, TextRange) ; dans les exemples, 
le curseur ne sert qua fournir un tel objet. 



Lire une zone de texte 

Un moyen pour lire du texte est de selectionner une zone grace aux deplacements de 
curseur, puis recuperer le texte ainsi selectionne avec la propriete String de l'objet 
curseur. Le document reste inchange. Dans cet exemple, nous allons recuperer puis 
afficher le troisieme paragraphe du document. 

rem Code08-01.odt bibli : EcritureTexte Module3 
Option Explicit 

Sub Af fi cherTexteSel ecti on () 

Dim monDocument As Object, monTexte As Object 

Dim monCurseur As Object 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

monCurseur = monTexte. createTextCursor 

monCurseur .gotoNext Paragraph (Fal se) 

monCurseur .gotoNext Paragraph (Fal se) 

monCurseur .gotoNext Paragraph (True) 

' afficher le texte du troisieme paragraphe 

MsgBox monCurseur. String 

End Sub 
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La propriete String est du type String. La selection ne doit pas englober plus de 
65 535 caracteres. 



Attention II y a String et String 

lei encore, le terme Stri ng est employe. II s'agit d'une propriete qui appartient a un objet curseur, elle 
est differente de la propriete Stri ng de I'objet Text. Chaque type d'objet peut utiliser n'importe quel 
nom pour ses proprietes et methodes. Pourquoi reprendre le meme nom ? parce que, au fond, ces pro- 
prietes designent des concepts similaires : une chaTne de caracteres representant un texte. Et une chame 
de caracteres, en anglais, cela s'appelle Stri ng. Ce nom est done aussi utilise en Basic et dans d'autres 
langages de programmation pour designer le type de variable « chame de caracteres ». Vous devez done 
comprendre le contexte pour employer un terme a bon escient. 



Inserer du texte 

Avec la propriete String 

En affectant une chaine de caracteres a la propriete String du curseur, nous allons 
inserer cette chaine a l'emplacement du curseur : 

rem Code08-01 . odt bibli : EcritureTexte Module4 
Option Explicit 

Sub AjouterTexteO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object 
monDocument = Thi sComponent 
monTexte = monDocument .Text 
monCurseur = monTexte. createTextCursor 
monCu rseu r . gotoNextParag raph (Fal se) 
monCu rseu r . gotoNextParag raph (Fal se) 
monCurseur . gotoNextWord(Fal se) 

' ajouter un texte apres le ler mot du 3eme paragraphe 
monCurseur. String = "*****'' 
End Sub 

Si nous avions utilise 1' argument True dans la methode gotoNextWord, le premier 
mot du paragraphe aurait ete remplace par la nouvelle chaine. 

Cette methode a des limitations : la taille de la chaine de caracteres inseree est 
bornee, on ne peut pas modifier le formatage, il faut deplacer le curseur par program- 
mation apres chaque ecriture de chaine sinon la suivante ecrasera la precedente. 
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A RETENIR Caracteres speciaux 

Dans la chame de caracteres inseree, un caractere chr(10) insere un saut de ligne et un caractere 
chr(9) insere une tabulation. 



Avec la methode insertString 

Avec cette methode, le curseur d'ecriture se positionne a la fin de la chaine de carac- 
teres ecrite, ce qui permet d'en inserer une autre a la suite. 

rem Code08-01.odt bibli : Ecri tureTexte Module5 
Option Explicit 

Sub InsererTexteO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object 
monDocument = Thi sComponent 
monTexte = monDocument. Text 
monCurseur = monTexte. createTextCursor 
monCurseur .gotoNext Paragraph (Fal se) 
monCurseur .gotoNext Paragraph (Fal se) 
monCurseur .gotoNextWord(Fal se) 

' ajouter un texte apres le ler mot du 3eme paragraphe 
monTexte. insertString(monCurseur, "AAAAA", false) 
monTexte. insertString(monCurseur, "bbbb", false) 
! End Sub 

La methode i nsertStri ng de l'objet Text utilise trois arguments : 

1 un objet curseur ; 

2 la chaine de caracteres a inserer ; 

3 une valeur booleenne. 

Le troisieme argument recoit en general la valeur Fal se. La valeur True est employee 
pour remplacer une zone prealablement selectionnee avec le curseur. Apres insertion, 
le curseur redevient ponctuel et positionne au debut de l'ancienne selection, c'est-a- 
dire juste avant\<t texte qui vient d'etre insere. 

Inserer des caracteres speciaux 

Dans la chaine de caracteres inseree avec la methode insertString, un caractere 
chr(10) insere un saut de ligne, et un caractere chr(9) insere une tabulation. La 
methode insertControl Character de l'objet Text permet d'inserer d'autres carac- 
teres speciaux. 
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rem Code08-01 . odt 
Option Explicit 



bibli : EcritureTexte Module6 



Sub InsererCarControleO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object 
Dim special As Integer 
monDocument = Thi sComponent 
monTexte = monDocument .Text 
monCurseur = monTexte. createTextCursor 
monCu rseu r . gotoNextParag raph (Fal se) 
monCurseur . gotoNextParag raph (Fal se) 
monCurseur . gotoNextWord(Fal se) 
monCurseur .gotoNextWord( Fal se) 

' inserer une fin de paragraphe apres 2eme mot 3eme paragraphe 
special = com. sun. star. text. Control Character. PARAGRAPH BREAK 
monTexte. insertControlCharacter (monCurseur , special, false) 

monTexte. insertString(monCurseur, "AAAAA" , false) 
End Sub 

Le premier argument de i nsertControlCharacter est un objet curseur. Le deuxieme 
argument est une valeur numerique du type Integer, qui se definit par une constante 
nommee (voir le tableau 8-3) de la forme : 



I 



com . sun . star . text . Control Character . LINE_BREAK 



Attention a la casse ! Les constantes nominees doivent etre ecrites en respectant les 
majuscules et minuscules. 

Le troisieme argument a la meme signification que pour i nsertStri ng. 
Tableau 8-3 Constantes de caracteres speciaux 



PARAGRAPH_BREAK 


Inserer ici une marque de fin de paragraphe. 




LINE_BREAK 


Inserer ici un retour a la ligne (equivalent de la frappe 
Maj + Entree). 


chr(10) 


HARD_HYPHEN 


Inserer ici un tiret insecable (le mot ne doit jamais etre 
coupe apres ce tiret). 


chr(8209) 


SOFT_HYPHEN 


Inserer ici un tiret conditionnel (le mot peut etre coupe a 
cet endroit). 


chr(173) 


HARD_SPACE 


Inserer ici un espace insecable (les deux mots ne doivent 
pas etre separes). 


chr(160) 


APPEND_PARAGRAPH 


Inserer un paragraphe a la fin de celui en cours et se 
positionner au debut du nouveau paragraphe. 
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Inserer un saut de page ou de colonne 

Le saut de page est une propriete de paragraphe. Vous pouvez definir un style de para- 
graphe comportant un saut de page. Sinon, vous pouvez inserer une marque de saut de 
page dans le paragraphe en cours grace a la propriete BreakType de l'objet curseur : 



rem Code08-01.odt 
Option Explicit 



bibli : EcritureTexte Module7 



Sub InsererSautPageO 

Dim monDocument As Object, monTexte As Object 

Dim monCurseur As Object 

Dim saut As Integer 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

monCurseur = monTexte. createTextCursor 

monCurseur .gotoNext Paragraph (Fal se) 

monCurseur .gotoNext Paragraph (Fal se) 

1 inserer un saut de page AVANT ce 3eme paragraphe 

saut = com. sun. star. style. BreakType. PACE BEFORE 

monCurseur. BreakType = saut 

monTexte. insertString(monCurseur, "AAAAA" , false) 
End Sub 

Dans le cas d'un document vierge ne contenant done pas de paragraphe, il est neces- 
saire d'inserer une fin de paragraphe avant le saut de page. Le saut est une valeur 
numerique du type Integer, qui se definit par une constante nommee (voir le 
tableau 8-4) de la forme : 

| com . sun . star . styl e . B reakType . NONE 

Tableau 8-4 Constantes de saut de page 



PAGE_BEFORE 


Changer de page avant le paragraphe en cours. 


PAGE_AFTER 


Changer de page apres le paragraphe en cours. 


PAGE_BOTH 


Changer de page avant et apres le paragraphe en cours. 


NONE 


Supprimer le saut de page ou de colonne qui existe dans le paragraphe. 


COLUMN_BEFORE 


Changer de colonne avant le paragraphe en cours. 


COLUMN_AFTER 


Changer de colonne apres le paragraphe en cours. 


COLUMN_BOTH 


Changer de colonne avant et apres le paragraphe en cours. 
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Les sauts de type COLUMN sont utilises dans un texte en colonnes. En effet, on peut 
avoir deux ou trois colonnes par page, et souhaiter changer de colonne sans obligatoi- 
rement changer de page. 

Pour inserer des pages d'orientation differente, par exemple passer d'une orientation 
Portrait a Paysage puis revenir a Portrait, il faut utiliser des styles de pages differents. 
La methode est developpee plus loin dans la section traitant des styles. 

Inserer le texte d'un autre document 

Le curseur d'ecriture expose la methode i nsertDocumentFromURL qui permet 
d'inserer un texte provenant d'un autre document. Pour cet exemple, recopiez au bon 
endroit le fichier Poeme . odt qui se trouve dans le Zip telechargeable, dans le meme 
repertoire, et adaptez la valeur d'adresseDoc. 

rem Code08-12 . odt bibli : Standard Modulel 
Option Explicit 

Sub InsererDocumentTexteO 

Dim monDocument As Object, monTexte As Object 

Dim monCurseur As Object, adresseDoc As String 

Dim propFichO As New com. sun. star. beans. PropertyVal ue 

monDocument = Thi sComponent 
monTexte = monDocument .Text 
monCurseur = monTexte. createTextCursor 
monCu rseu r . gotoNextParag raph (Fal se) 

monCurseur. gotoNextParagraph(False) ' troisieme paragraphe 
monCurseur. gotoNextWord(True) 1 selectionner le premier mot 

' inserer un document a la place du texte selectionne 
adresseDoc = convertToURL("C:\Docs OpenOff i ce\Poeme . odt") 
monCurseur . insertDocumentFromURL(adresseDoc , propFichO) 
End Sub 

Largument propFichO peut contenir les proprietes listees au chapitre 7 pour la 
methode LoadComponentFromURL. 

Vous remarquerez que les styles du document insere sont importes dans le document 
hote. En revanche, les en-tetes et has de pages ne sont pas importes. 



Supprimer des paragraphes 

II faut distinguer la suppression d'une marque de paragraphe et la suppression com- 
plete d'un paragraphe. 
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Supprimer une marque de paragraphe 

Une marque de paragraphe est un caractere special dans le texte. On peut done la sup- 
primer comme on supprimerait un caractere du texte, ce qui aboutit a accoler le texte 
du paragraphe avec le paragraphe suivant. Notre exemple parcourt un texte complet et 
supprime les marques de paragraphe en remplacant chacune par un espace. 

rem Code08-ll.odt bibli : Standard Modulel 
Option Explicit 

Sub Supprimer_MarquesParag raphes () 

Dim monDocument As Object, monTexte As Object 

Dim monCurseur As Object 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

monCurseur= monTexte . createTextCursor 

monCurseur .gotoStart(fal se) 

Do While monCurseur .gotoNextParagraph(false) 

monCurseur .goLeft(l, true) 

monCurseur .String = " " 
Loop 
End Sub 

Le texte de l'exemple dans le Zip telechargeable est un poeme dont chaque strophe 
est un paragraphe comportant un retour a la ligne pour chaque vers. Les paragraphes 
ont differents styles. Apres execution de la macro, les retours a la ligne sont con- 
serves, mais a chaque suppression de fin de paragraphe, la strophe correspondante a 
pris le style de la strophe suivante. 



Supprimer tout un paragraphe 

Lobjet texte d'un document Writer est capable d'enumerer les paragraphes qui le 
composent. Cependant, cette enumeration contient egalement les tables du texte, 
aussi est-il necessaire de verifier que 1' element obtenu supporte le service de para- 
graphe. Nous allons dans l'exemple suivant supprimer entierement les paragraphes 
ayant un style donne. 

rem Code08-ll.odt bibli : Standard Module2 
Option Explicit 

Sub Suppr_paragr_style() 

Dim monDocument As Object 

Dim listePargr As Object, elementTexte As Object 

Dim uneSuppression As Boolean 
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monDocument = Thi sComponent 
Do 

uneSuppression = false 

"HstePargr = monDocument. Text. createEnumerati on 
Do While 1 i stePargr . hasMoreEl ements 
elementTexte = li stePargr. nextElement 

i f el ementTexte . supportsServi ce("com . sun . star . text . Paragraph") Then 

"if elementTexte. paraStyl eName= "monStyle" then 
el ementTexte . di spose 
uneSuppression = true 
end if 
end if 
Loop 

Loop While uneSuppression 
End Sub 

La boucle While la plus externe est necessaire pour ne pas « oublier » certains para- 
graphes. La fonction createEnumeration de l'objet texte renvoie un objet capable, 
d'une part de signaler 1' existence d'elements non encore vus (la fonction 
hasMoreEl ements qui renvoie alors true), et d'autre part de fournir chacun d'eux 
(avec la fonction nextElement). Pour distinguer les elements paragraphes, nous 
employons la fonction supportsServi ce. Le style d'un paragraphe est expose dans la 
propriete ParaStyl eName. 

A 1' execution de la macro, vous constaterez que les paragraphes non concernes ont 
bien conserve leur style. 



Appliquer un formatage 

Le moyen le plus efficace de formater un texte avec une macro est de lui appliquer 
des styles definis au prealable. Le plus simple est de partir d'un document modele 
ecrit manuellement, dans lequel on a defini les styles necessaires. 

Appliquer un style a un paragraphe 

Le curseur d'ecriture possede une propriete appelee ParaStyl eName qui indique le 
nom du style du paragraphe dans lequel le curseur se trouve. Cette propriete est une 
chaine de caracteres. La macro suivante affecte le style Titre4 au deuxieme para- 
graphe du document en cours. 

rem Code08-02 . odt bibli : Formatage Modulel 
Option Explicit 
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Sub AffecterStyleParagrapheO 

Dim monDocument As Object, monTexte As Object 

Dim monCurseur As Object 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

monCurseur= monTexte . createTextCursor 

monCurseur .gotoNext Paragraph (fal se) 

monCurseur. paraStyleName= "Titre 4" 

End Sub 

Le curseur d'ecriture peut etre dans une position quelconque dans le paragraphe. 
Inversement, la lecture de la propriete paraStyleName fournit le nom du style du 
paragraphe dans lequel se trouve le curseur. 



PlEGE Les noms de styles traduits 

Pour les styles standards fournis avec OpenOffice.org, vous recuperez dans paraStyl eName le nom 
anglais du style, meme avec une version francisee. Dans la macro exemple, on affecte le style Titre 4 et 
on relira le style Heading 4. En revanche, les styles que vous creez n'ont evidemment qu'un seul nom. 
L'annexe B offre une fonction getLocal eStyl eName qui traduit un nom de style anglais dans son 
nom localise. 



Attention a la casse ! La chaine de caracteres du style que vous affectez doit repro- 
duce exactement le nom du style existant : majuscules, minuscules, accents. Sinon le 
style du paragraphe restera inchange. 

Appliquer un style a un ou plusieurs caracteres 

Le curseur d'ecriture possede une propriete appelee CharStyleName, qui indique le 
nom du style du caractere courant ou des caracteres selectionnes par le curseur. Cette 
propriete est une chaine de caracteres. Cette macro selectionne une zone et lui 
applique un style de caracteres. 

rem Code08-02 . odt bibli : Formatage Module2 
Option Explicit 

Sub AffecterStyleCaractereO 

Dim monDocument As Object, monTexte As Object 

Dim monCurseur As Object 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

monCurseur= monTexte .createTextCursor 

monCurseur .gotoNext Paragraph (fal se) 

monCurseur .gotoNextWord(fal se) 
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monCurseur . gotoEndOfWord(true) 

monCurseur .CharStyleName = "MonStyl eCaract" 

End Sub 

La propriete CharStyleName peut fournir le nom du style d'un caractere selectionne, 
a condition qu'il ne soit pas formate « Par defaut ». Pour les styles de caracteres stan- 
dards fournis avec OpenOffice.org, vous obtiendrez le nom anglais du style, meme 
avec une version francisee. Si vous selectionnez plusieurs caracteres de styles diffe- 
rents, la propriete CharStyleName donne une chaine vide. 



Formatage d'un paragraphe 

L'objet curseur nous donne acces au paragraphe dans lequel il se trouve (on suppose 
ici qu'il ne s'etend pas sur plusieurs paragraphes). Un paragraphe contient de nom- 
breuses proprietes, que nous pouvons lire ou modifier, comme avec l'interface utilisa- 
teur, menu Format>Paragraphe. Le tableau 8-5 enumere les principales proprietes, 
dont certaines ont deja ete vues. 

Tableau 8-5 Proprietes de paragraphe 



ParaStyl eName 


Stri ng 


Nom du style affecte au paragraphe. 


ParaBackCol or 


Long 


Couleur du fond. 


ParaBackTrans parent 


Boolean 


True rend le fond transparent (interface utilisateur : sans remplis- 
sage). 


ParaAdjust 


Integer 


Alignement du texte. Constante nommee, voir tableau 8-6. Valeur 
par defaut : 

com . sun . star . styl e . ParagraphAd j ust .LEFT 


ParaFi rstLi nelndent 


Long 


Retrait de la premiere ligne, en 1/100 de mm. 


ParalsAutoFi rstLi nelndent 


Bool ean 


True realise un retrait automatique de la premiere ligne. 


ParaVertAl i gnment 


Integer 


Alignement vertical du texte (interface utilisateur : alignement texte 
a texte). Constante nommee, voir le tableau 8-7. Valeur par defaut : 
com . sun . star . text . ParagraphVertAl i gn .AUTOMATIC 


ParalsConnect Border 


Bool ean 


True pour fusionner la bordure avec celle du paragraphe suivant. 


TopBorder 


Object 


Structure de la ligne de bordure du haut. Voir le tableau 8-8. 


TopBorderDi stance 


Long 


Espacement par rapport a la bordure du haut. 


BottomBorder 


Object 


Structure de la ligne de bordure du bas. Voir le tableau 8-8. 


BottomBorderDi stance 


Long 


Espacement par rapport a la bordure du bas. 


LeftBorder 


Object 


Structure de la ligne de bordure de gauche. Voir le tableau 8-8. 


LeftBorderDi stance 


Long 


Espacement par rapport a la bordure de gauche. 


Ri ghtBorder 


Object Structure de la ligne de bordure de droite. Voir le tableau 8-8. 
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Tableau 8-5 Proprietes de paragraphe (suite) 







Signification 


Ri ghtBorderDi stance 


Long 


Espacement par rapport a la bordure de droite. 


ParaShadowFormat 


Object 


Ombre portee. Voir le tableau 8-9. 


ParaTopMargi n 


Long 


Ecart avant le paragraphe, en 1/100 de mm. 


ParaBottomMargi n 


Long 


Ecart apres le paragraphe, en 1/100 de mm. 


ParaLef tMargi n 


Long 


Retrait avant le texte, en 1/100 de mm. 


ParaRi ghtMargi n 


Long 


Retrait apres le texte, en 1/1 00 de mm. 


ParaTabStops 


Object 


Position des taquets de tabulation. Voir la section « Def ini r des posi- 
tions de tabulations. 


ParaKeepTogether 


Boolean 


True si ce paragraphe est solidaire avec le paragraphe suivant. 


ParaSplit 


Boolean 


True si les lignes sont solidaires. 

Fal se pour utiliser le traitement des veuves et orphelines. 


ParaOrphans 


Integer 


Nombre de lignes orphelines. 


ParaWidows 


Integer 


Nombre de lignes veuves. 


ParalsNumberi ngRestart 


Boolean 


True si la numerotation redemarre. 


Numberi ngStartVal ue 


Integer 


Valeur initiale en cas de redemarrage de numerotation. 


BreakType 


Integer 


Saut de page ou de colonne. Constante nommee, voir le 
tableau 8-4. 



Tableau 8-6 Constantes d'alignement horizontal de paragraphe 



LEFT 


Texte cadre a gauche. 


RIGHT 


Texte cadre a droite. 


CENTER 


Texte centre. 


STRETCH 


Texte justifie. 


BLOCK 


Texte justifie, sauf la derniere ligne qui depend alors de 
ParaLastLi neAdjust 


Tableau 8-7 Constantes d'alignement vertical de paragraphe 


Constante Signification 


AUTOMATIC 


Automatique. 


BASELINE 


Ligne de base. 


TOP 


En haut. 


CENTER 


Centre. 


BOTTOM 


En bas. 
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Tableau 8-8 Structure BorderLine (ligne de bordure) 



Element Type Signification 


Color Long 


Couleur de la ligne. 


InnerLi neWidth 


Integer 


Epaisseur de la ligne interne, en 1 /1 00 de mm, dans le cas d'une bor- 
dure double. La valeur zero correspond a une bordure simple. 


OuterLi neWidth 


Integer 


Epaisseur, en 1/100 de mm, de la ligne simple ou de la ligne exteme 
dans le cas d'une bordure double. La valeur zero correspond a une 
bordure inexistante. 


Li neDi stance 


Integer 


Distance entre les deux lignes d'une bordure double, en 1/100 de mm. 



II est necessaire de passer par une variable de travail pour modifier le contenu d'une 
bordure : 

Dim unBord As Object 

unBord = monCurseur .TopBorder 

unBord. Color = RCB(200, 0, 0) ' couleur rouge 

unBord . InnerLi neWidth = 10 ' 1/10 de mm 

unBord. OuterLi neWidth = 100 ' 1 mm 

unBord . Li neDi stance = 120 1 1,2 mm 

monCurseur. TopBorder = unBord 

Tableau 8-9 Structure de Shadow/Format 



Location 


Integer 


Position de I'ombre, sous forme de constante nommee, voir le tableau 8-10. 


ShadowWi dth 


Integer 


Largeur de I'ombre en 1 /1 00 de mm. 


IsTransparent 


Bool ean 


True si I'ombre est transparente. 


Color 


Long 


Couleur de I'ombre. 



La position de I'ombre est exprimee sous forme de constante nommee (voir le 
tableau 8-10), par exemple : 

com . sun . star . tabl e . ShadowLocati on . BOTTOM RIGHT 

Tableau 8-10 Constantes de position d'ombre 



NONE 


Aucune ombre. 


T0P_LEFT 


Ombre portee vers le haut et a gauche. 


T0P_RICHT 


Ombre portee vers le haut et a droite. 


B0TT0M_LEFT 


Ombre portee vers le bas et a gauche. 


B0TT0M_RIGHT 


Ombre portee vers le bas et a droite. 
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II est necessaire de passer par une variable de travail pour modifier le contenu de 
ParaShadowFormat : 

Dim ombre As Object 

ombre = monCurseur . ParaShadowFormat 

ombre . Location = com. sun. star. table. Shadow/Location. TOP LEFT 
ombre . Shadow/Width = 200 ' environ 3 , 5 mm 
ombre. Col or = RGB (100 , 100 , 100) ' couleur grise 
maTable. Shadow/Format = ombre 
End Sub 



Formatage local des caracteres 

L'objet curseur nous donne aussi acces aux proprietes du ou des caracteres sur lesquels il 
s'etend, nous donnant des possibilites equivalentes au menu Format>Caracteres. La 
methode est identique dans chaque cas, seul le premier est traite en exemple complet. 

Graisse 

En terme d'imprimerie, la graisse est l'epaisseur des pleins de la lettre. On utilise la 
propriete CharWei ght de type Si ngl e, a laquelle on affecte une constante nommee de 
la forme : 

com . sun . star . awt . FontWei ght . NORMAL 

Cet exemple met un mot en gras. 

rem Code08-02 .odt bibli : Formatage Module3 
Option Explicit 

Sub FormaterCaracteresO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object 
monDocument = Thi sComponent 
monTexte = monDocument. Text 
monCurseur= monTexte . createTextCursor 
monCurseur .gotoNext Paragraph (fal se) 
monCurseur .gotoNextWord(fal se) 
monCurseur . gotoEndOfWord(true) 

monCurseur .CharWei ght = com. sun. star. awt. FontWeight. BOLD 

End Sub 

Les differentes valeurs de constantes possibles sont listees dans le tableau 8-11, du 
plus maigre au plus gras. II s'agit de nombres reels : par exemple 150 % vaut 1,5. 

Attention a la casse ! Les constantes nominees doivent etre ecrites en respectant les 
majuscules et minuscules. 
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Tableau 8-11 Constantes de graisse 



THIN 


Fin. 


50% 


ULTRALIGHT 


Ultra-maigre. 


60% 


LIGHT 


Maigre. 


75% 


SEMILIGHT 


Semi-maigre. 


90% 


NORMAL 


Normal. 


100% 


SEMIBOLD 


Semi-gras. 


110% 


BOLD 


Gras. 


150% 


ULTRABOLD 


Ultra-gras. 


1 75% 


BLACK 


Noir. 


200% 



Italique 

L'italique est reglee par la propriete CharPosture de type Integer, qui a deux valeurs 
possibles : 



com . sun . star . awt . FontSl ant . NONE 
com . sun . star . awt . FontSl ant . ITALIC 



La valeur NONE donne un caractere droit, l'autre donne un caractere en italique. 



Soulignement et surlignement 

De meme qu'un soulignement realise un trace en-dessous d'un caractere, nous utili- 
sons ici le mot surlignement pour designer Faction d'executer un trace au-dessus d'un 
caractere. Le surlignage, equivalent au passage d'un feutre sur les caracteres, est traite 
un peu plus loin a la section « Couleurs » car il s'agit de la couleur de fond. Souligne- 
ment et surlignement fonctionnent de maniere identique. 

• La propriete CharUnderl i ne realise le soulignement de caractere. 

• La propriete CharOverl i ne, seulement disponible a partir de la version 3.1 
d'OpenOffice.org, realise le surlignement de caractere. 

Ces deux proprietes recoivent chacune une constante nommee (voir le tableau 8-12) 
qui precise le trait. La meme serie FontUnderl i ne est utilisee pour les valeurs des 
deux proprietes. Prenons un exemple : 

com . sun . star . awt . FontUnderl i ne . SINGLE 
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Tableau 8-12 Constantes de trait 



Constante 


Resultat 


NONE 


Aucun trait. 


SINGLE 


Ligne unique. 


DOUBLE 


Ligne double. 


DOTTED 


Ligne pointillee. 


DASH 


Ligne de tirets. 


LONGDASH 


Ligne de tirets longs. 


DASHDOT 


Tiret-point. 


DASHDOTDOT 


Tiret-point-point. 


SMALLWAVE 


Petite ondulation. 


WAVE 


Ondulation. 


DOUBLEWAVE 


Double ondulation. 


BOLD 


Ligne grasse. 


BOLDDOTTED 


Ligne pointillee en gras. 


BOLDDASH 


Ligne de tirets gras. 


BOLDLONGDASH 


Ligne de tirets longs et gras. 


BOLDDASHDOT 


Tiret-point gras. 


BOLDDASHDOTDOT 


Tiret-point-point gras. 


BOLDWAVE 


Ondulation grasse. 



Le soulignement comme le surlignement peuvent prendre une autre couleur que 
celle du caractere, voyez un peu plus loin la section sur les couleurs. 

Notez aussi la propriete CharWordMode, de type Boolean : si sa valeur est True, les 
espaces ne seront pas soulignes ou surlignes. 



Accentuation 

Ce type de surlignement ou de soulignement est prevu pour les caracteres asiatiques, 
mais peut etre utile pour enjoliver certains textes. La propriete CharEmphasi s recoit 
une constante nommee de la forme : 

com . sun . star . text . FontEmphasi s . DOT ABOVE 
Le tableau 8-13 liste les differentes valeurs. 
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Tableau 8-13 Constantes d'accentuation 



NONE 


Pas d'accentuation. 


DOT_ABOVE 


Un point au-dessus du caractere. 


CIRCLE_ABOVE 


Un cercle au-dessus du caractere. 


DISK_ABOVE 


Un disque au-dessus du caractere. 


ACCENT_ABOVE 


Un accent au-dessus du caractere. 


DOT_BELOW 


Un point au-dessous du caractere. 


CIRCLE_BELOW 


Un cercle au-dessous du caractere. 


DISK_BELOW 


Un disque au-dessous du caractere. 


ACCENT_BELOW 


Un accent au-dessous du caractere. 



Relief 

La propriete CharRelief, de type Integer, dessine un effet de relief au caractere. 
Ceci n'est visible que sur une taille suffisamment grande. La propriete recoit une des 
trois constantes nominees : 

com. sun . star . text . FontRel i ef. NONE ' aucun relief 
com. sun. star. text. FontRelief .EMBOSSED ' grave en relief 
com . sun . star . text . FontRel i ef. ENGRAVED ' grave en creux 



Changement de casse 

La propriete CharCaseMap transforme la casse du caractere ; elle utilise des constantes 
nominees (tableau 8-14) de la forme : 

com . sun . star . styl e . CaseMap . NONE 

Tableau 8-14 Constantes de changement de casse 



NONE 


La casse n'est pas modifiee. 


UPPERCASE 


Le caractere est mis en majuscules. 


LOWERCASE 


Le caractere est mis en minuscules. 


TITLE 


Le premier caractere de chaque mot est mis en majuscule. 


SMALLCAPS 


Le caractere est mis en petite minuscule. 
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Exposant et indice 

Mettre un caractere en exposant ou en indice necessite deux proprieties de type 
Integer : 

• CharEscapement specifie la position verticale du caractere par rapport a un carac- 
tere normal, en pourcentage de la hauteur de la police : une valeur positive pour 
un exposant, une valeur negative pour un indice. 

• CharEscapementHeight specifie la taille du caractere, en pourcentage, par rapport 
a la taille de la police. La valeur est positive. 

Void un exemple : 

' position : plus haut de 20% de la hauteur de la police 

monCurseur .CharEscapement = 20 

' taille : 70% de la taille de la police 

monCurseur .CharEscapementHeight = 70 



Astuce 

Les valeurs de position du caractere sont visibles avec I'interface utilisateur. Pour cela, selectionnez le 
caractere et ouvrez le menu Format>Caracteres... a I'onglet Position. 



Attention 

La documentation de I'API pour la propriete CharEscapementHeight indique a tort qu'elle peut 
prendre des valeurs negatives. 



Couleurs 

Les proprietes de caractere indiquant une couleur sont listees dans le tableau 8-15. 
Le codage des couleurs et la fonction RGB sont expliques au chapitre 5. 

Tableau 8-15 Proprietes de couleur de caractere 



CharColor 


Long 


Couleur de la police de caractere. La valeur -1 correspond a la couleur 
Automatique. 


CharBackColor 


Long 


Couleur de I'arriere-plan. La valeur -1 correspond a Sans 
rempl i ssage. 


CharBackTransparent 


Bool ean 


True si la couleur de fond n'est pas utilisee. 


CharUnderl i neCol or 


Long 


Couleur de soulignement. La valeur -1 correspond a la couleur 
Automatique. 
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Tableau 8-15 Proprietes de couleur de caractere (suite) 



CharUnderli neHasColor 


Boolean 


True pour imposer la couleur de soulignement. 

Fal se pour que le soulignement prenne la meme couleur que le 

caractere. 


CharOverl i neCol or 


Long 


Couleur de surlignement. La valeur -1 correspond a la couleur 
Automatique. 


CharOverl i neHasCol or 


Boolean 


True pour imposer la couleur de surlignement. 

Fal se pour que le surlignement prenne la meme couleur que le 

caractere. 



Exemple 



monCurseur.CharColor = RGB(250,0,0) 
monCurseur.CharBackColor = 1234567 



La couleur Automatique de la police de caracteres se traduit par du noir si l'arriere- 
plan est clair, ou du blanc si l'arriere-plan est (tres) sombre. La valeur -1 doit etre 
appliquee directement car la fonction RGB ne peut la fournir. 



Rotation de caracteres 

Ceci correspond au menu Format>Caracteres, onglet Position>Rotation. La propriete 
CharRotation, de type Single, est Tangle de rotation exprime en dixiemes de 
degres ; les seules valeurs acceptees correspondent a 0, 90 et 270 degres. 

monCurseur. CharRotation = 900 

La propriete CharRotationlsFitToLi ne, de type Boolean, correspond a la case 
Adapter a la ligne dans le meme panneau d'interface utilisateur. La valeur True revient 
a cocher la case. 



Barrer un caractere 

Barrer un caractere peut se faire de deux manieres differentes, avec la propriete 
CharCrossedOut ou la propriete CharStri keOut. Si on modifie l'une, l'API modifiera 
l'autre en coherence. 

Pour barrer d'une ligne simple, il suffit de mettre a True la propriete 
CharCrossedOut. 

monCurseur. CharCrossedOut = True 
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Avec CharStri keOut, de type Integer, on dispose de plusieurs styles de barres, 
comme le montre le tableau 8-16. Ce sont des constantes nominees utilisees ainsi : 

monCurseur .CharStrikeOut = com . sun . star . awt . FontStri keout .SLASH 
Tableau 8-16 Constantes pour barrer un caractere 







NONE 


Caractere non barre. 


SINGLE 


Barre d'une ligne simple. 


DOUBLE 


Barre d'une ligne double. 


BOLD 


Barre d'une ligne en gras. 


SLASH 


Barre avec des traits «barre de fraction)). 


X 


Barre de deux traits en «X» 



Autres proprietes de caractere 

Ces proprietes diverses sont listees dans le tableau 8-17. 

Tableau 8-17 Autres proprietes de formatage de caractere 



CharStyl eName 


String 


Nom du style de caractere (respecter la casse). 


CharFontName 


String 


Nom de la police de caracteres (respecter la casse). 


CharHeight 


Single 


Taille du caractere, en points, exemple : 9,7. 
Un point vaut 1/72 de pouce, soit 0,3527 mm 


CharShadowed 


Boolean 


Valeur True pour ombrer le caractere. 


CharHi dden 


Boolean 


Valeur True pour rendre invisible le caractere. 


CharContoured 


Boolean 


Valeur True pour dessiner un contour du caractere 
(visible sur une grande taille). 


CharScaleWidth 


Integer 


Echelle de la largeur du caractere, en pourcentage de la 
taille normale (100), exemple : 150 ou 57 


CharWordMode 


Boolean 


Valeur True pour ne pas appliquer le soulignement, le 
surlignement ou le barre sur les espaces entre mots. 


CharFlash 


Boolean 


Valeur True pour faire clignoter le caractere a I'ecran. 


CharLocale 


Object 


Langue utilisee pour les fonctions dependant de la loca- 
lisation. Voir la notion de Locale dans le chapitre 7. 
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Supprimer tout formatage de caractere 

Pour tout nettoyer, c'est-a-dire ne kisser que le formatage propre au style du paragraphe 
en cours, on applique la methode setAl 1 Properti esToDefaul t de l'objet curseur. 

monCurseu r . setAi 1 Properti esToDef aul t 

Pour remettre une propriete de formatage a sa valeur par defaut, utilisez la methode 
setPropertyToDefault en precisant la propriete souhaitee : 

monCurseu r . setPropertyToDefaul t("CharHeight") 



Curseur visible et zone selectionnee par l'utilisateur 

Obtenir le curseur visible 

Le curseur visible, c'est la barre verticale clignotante affichee sur votre texte a l'ecran. 
C'est aussi une zone selectionnee par l'utilisateur, par exemple en faisant glisser la 
souris sur le texte. 

L'objet curseur visible ne s'obtient pas directement de l'objet document, mais de 
l'objet controleur associe a la fenetre courante du document. 

Dim monDocument As Object 
Dim CurseurVisible As Object 
monDocument = Thi sComponent 

curseurVisible = monDocument. Cur rentController .View/Cursor 

II n'existe qu'un seul curseur visible (alors qu'on peut creer plusieurs curseurs d'ecri- 
ture). La variable curseurVisible reflete l'etat reel du curseur visible : s'il evolue sous 
Faction de l'utilisateur, la variable pointe sur la nouvelle zone. 

Zone selectionnee par l'utilisateur 
Modifier le contenu de la zone 

Le curseur visible connait la ou les zones selectionnees par l'utilisateur. Le formatage 
de ces zones peut etre realise en employant directement le curseur visible comme un 
curseur d'ecriture. Par exemple, la macro suivante, bien pratique, affecte un style de 
caractere aux zones selectionnees par l'utilisateur. II suffit ensuite de declencher la 
macro par un raccourci clavier ou un nouveau bouton sur une barre d'outils. 
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Sub Styl eCarPerso 

Dim CurseurVisible As Object 

CurseurVisible = ThisComponent.Currentcontroller.ViewCursor 
CurseurVisible. CharStyleName = "MonStyl eCaract" 
End Sub 

Void comment recuperer le texte selectionne par l'utilisateur et le remplacer par un 
autre texte, en utilisant la propriete Stri ng du curseur visible : 

rem Code08-01 . odt bibli : Sel ectionTexte Modulela 
Option Explicit 

Sub Mani pul erSel ecti onLIti 1 i sateu r () 

Dim monDocument As Object, CurseurVisible As Object 

Dim texteSel As String 

monDocument = Thi sComponent 

CurseurVisible = monDocument. CurrentController.ViewCursor 
texteSel = CurseurVisible. String 
print texteSel 

CurseurVisible. String = "BBBBB" 
End Sub 



Definir un curseur d'ecriture sur la zone selectionnee 

Malheureusement, la variable CurseurVisible nest pas un curseur d'ecriture, mais 
un curseur d'un autre type, moins elabore. Pour creer un curseur d'ecriture equiva- 
lent, nous devons d'abord determiner dans quel texte se trouve le curseur visible. En 
effet, il peut se trouver ailleurs que dans le texte principal, par exemple dans un 
tableau du document, ou un en-tete, ou encore un pied de page. L'objet texte corres- 
pondant nous est donne par la pseudo-propriete Text du curseur visible. 

Dim monTexte As Object 
monTexte = CurseurVisible. Text 

Pour obtenir un curseur d'ecriture a partir d'une zone selectionnee, nous allons uti- 
liser la methode deja vue dans la section « Creer un curseur a partir d'un autre 
curseur » : 

Dim unCurseur As Object 

unCurseur = monTexte. createTextCursorByRange(CurseurVisible) 
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Nous pouvons preciser si le curseur d'ecriture couvre la zone de selection du curseur 
visible ou s'il est un point d'insertion en debut ou fin de zone : 

' curseur positionne sur la derniere selection effectuee 

unCurseur = monTexte.createTextCursorByRange(CurseurVisible) 

' curseur au debut de la derniere selection effectuee 

unCurseur = monTexte . createTextCursorByRange(CurseurVisible.Start) 

' curseur a la fin de la derniere selection effectuee 

unCurseur = monTexte . createTextCursorByRange(CurseurVisible. End) 

S'il n'y a pas de selection, ces trois instructions donnent le meme resultat. En cas de besoin, 
on determine s'il y a une selection avec la fonction i sCol 1 apsed de l'objet curseur : 

unCurseur = monTexte. createTextCursorByRange(CurseurVisible) 
if unCurseur . isColl apsed then 

' ici pas de selection 
el se 

' ici il y a une selection 
end if 

Obtenir l'objet texte de la selection 

Reprenons l'exemple precedent avec quelques modifications. 

rem Code08-01 . odt bibli : Sel ecti onTexte Modulelb 
Option Explicit 

Sub Mani pul erTouteSel ectionUti 1 i sateur () 

Dim monDocument As Object, CurseurVi si bl e As Object 

Dim monCurseur As Object, monTexte As Object 

Dim texteSel As String 

monDocument = Thi sComponent 

CurseurVisible = monDocument. CurrentController.ViewCursor 
monTexte = CurseurVisible. Text 

monCurseur = monTexte. createTextCursorByRange(CurseurVisible) 

texteSel = monCurseur . Stri ng 

print texteSel 

monCurseur. String = "BBBBB" 

End Sub 

Maintenant, la variable monTexte ne represente plus systematiquement le texte principal 
du document, mais une zone de texte quelconque. Nous pouvons lire et modifier une 
zone selectionnee par l'utilisateur, meme dans un en-tete, un bas de page, un tableau, etc. 

Ce code marche correctement si l'utilisateur a selectionne une seule zone dans le 
texte principal. Cependant, on peut selectionner plusieurs zones simultanement, en 
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utilisant la touche Ctrl avec glissement de la souris, pour les zones supplementaires. 
Et dans ce cas, la propriete Stri ng fournit une chaine nulle. 

L'objet CurrentSelection de l'objet document fournit une liste des zones selection- 
nees. On utilise alors une boucle pour trouver successivement ces zones. Le nombre 
de zones est dans la propriete Count de l'objet CurrentSelection. Pour chaque zone, 
on cree un curseur d'ecriture suivant la methode precedemment exposee. L'exemple 
suivant met en caracteres gras les zones selectionnees par l'utilisateur. 

rem Code08-01 . odt bibli : Sel ectionTexte Module2 
Option Explicit 

Sub Bal ayerSel ecti onsUti 1 i sateurO 

Dim monDocument As Object 

Dim lesZones As Object, uneZone As Object 

Dim monCurseur As Object, monTexte As Object 

Dim x As Long 

monDocument = Thi sComponent 

lesZones = monDocument. CurrentSelection 

for x = 0 to lesZones. Count -1 

uneZone = lesZones(x) ' raccourci pour . getBylndex(x) 
monTexte = uneZone. Text 

monCurseur = monTexte . createTextCursorByRange(uneZone) 

if not monCurseur. isCol lapsed then 

monCurseur.CharWeight = com . sun . star . awt . FontWei ght . BOLD 

end if 
next 
End Sub 

L'instruction lesZones (x) est un raccourci de Basic pour lesZones. getBylndex(x) : 
l'objet lesZones est un conteneur, et getBylndex une methode renvoyant un des 
objets du conteneur. C'est la raison pour laquelle nous n'employons pas ici la struc- 
ture for each. 

Si vous n'etes pas sur que l'utilisateur n'a selectionne qu'une seule zone, employez le 
codage ci-dessus. S'il n'y a aucune selection, la boucle for est executee une fois. Le 
test i sCol 1 apsed evite de mettre en gras si la zone est ponctuelle. 

Ou se trouve le curseur ? 

L'objet curseur (curseur visible ou curseur d'ecriture) offre plusieurs proprietes qui 
nous donnent des informations sur son environnement ; d'abord, sur le texte lui- 
meme, qui n'est pas toujours le texte principal. La distinction se fait par le contenu de 
la propriete ImplementationName de l'objet texte : 

pri nt Cu rseu rVi si bl e . Text . Impl ementationName 
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Cette propriete, de type Stri ng, nous renseigne sur la variante d'objet texte : 

• SwXBodyText : le texte principal ou le texte dans un dessin ; 

• SwXText Frame : le texte dans un cadre ; 

• SwXCel 1 : le texte dans une cellule de tableau ; 

• SwXHeadFootText : le texte d'un en-tete ou bas de page ; 

• SwXFootnote : le texte d'une note de bas de page ou d'une note de fin. 

De plus, le curseur expose plusieurs proprietes permettant de remonter a l'objet dans 
lequel il se trouve : 

• TextTabl e est le tableau ; 

• Cel 1 est la cellule dans le tableau ; 

• TextFrame est le cadre ; 

• TextFi el d est le champ de texte ; 

• TextSection est la section. 

Lorsque le curseur n'est pas dans une de ces zones, la propriete correspondante n'est 
pas disponible. Pour eviter une erreur d'execution, on utilise la fonction OOoBasic 
IsEmpty : 

if IsEmpty(CurseurVisible.TextTable) then 

print "En dehors d'un tableau" 
el se 

MsgBox("Tableau : " & Cu rseurVi si ble. TextTabl e. Name & 

chr(13) & "Cellule : " & CurseurVi si ble. Cell .Cell Name) 

end if 

Si vous avez l'intention d'analyser un document inconnu avec ces informations, 
n'oubliez pas que les combinaisons sont possibles, par exemple un tableau dans un 
cadre dans le texte d'une section elle-meme incluse dans une section... Pour etudier 
les possibilites, utilisez l'outil Xray decrit a l'annexe A. 

Explorer la zone selectionn.ee par I'utilisateur 

Nous allons reprendre le code donne precedemment, qui supprime des paragraphes. 
Cette nouvelle version ne supprime les paragraphes que dans la zone selectionnee par 
I'utilisateur : 

rem Code08-01.odt bibli : Sel ecti onTexte Module3 
Option Explicit 

Sub Expl orerSel ecti onLIti 1 i sateu r () 

Dim monDocument As Object, monTexte As Object 
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Dim CurseurVisible As Object, monCurseur As Object 
monDocument = Thi sComponent 

CurseurVisible = monDocument. CurrentController.ViewCursor 
monTexte = CurseurVisible. Text 

' creer un curseur a la position de debut du curseur visible 
monCurseur = monTexte. createTextCursorByRange (Cur seurVi si bl e. Start) 
Do While monCurseur. gotoNextParagraph(false) 
if monTexte. compareRegionEnds (monCurseur, 

CurseurVisible)< 0 then Exit Do 

monCurseur. goLeft(l, true) 

monCurseur. String = " " 
Loop 
End Sub 

Notez que, si l'utilisateur selectionne plusieurs zones, la macro ne supprime rien. 

La fonction compareRegionEnds de la variable objet monTexte compare les positions 
de fin dans les deux curseurs. Elle renvoie : 
1 si le premier curseur se termine avant le deuxieme ; 

0 si les deux se terminent a la meme position ; 

-1 si le premier curseur se termine apres le deuxieme. 

II existe aussi la fonction compareRegionStarts, qui renvoie : 

1 si le premier curseur commence avant le deuxieme ; 
0 si les deux commencent a la meme position ; 

-1 si le premier curseur commence apres le deuxieme. 

Selectionner de maniere visible une zone de texte 

Apres avoir selectionne une zone en deplacant un curseur d'ecriture, vous voulez affi- 
cher cette selection a l'utilisateur. On utilise pour cela une methode de l'objet 
CurrentControl 1 er : 

rem Code08-01.odt bibli : Sel ectionTexte Module4 
Option Explicit 

Sub AfficherSelectionO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object 
monDocument = Thi sComponent 
monTexte = monDocument. Text 
monCurseur = monTexte. createTextCursor 
monCurseur .gotoNext Paragraph (Fal se) 
monCurseur .gotoNextWord(fal se) 

monCurseur. gotoEndOfWord(true) ' selectionner un mot 
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monDocument .CurrentControl 1 er . Sel ect(monCurseur) 

End Sub 

La methode Sel ect utilise en argument un objet curseur, qui indique la zone de texte 
a afficher comme selection. Le document exemple du Zip telechargeable contient 
deux pages. Si la fenetre Writer est sur la premiere page, 1' execution de la macro fera 
derouler le texte pour afficher la nouvelle position du curseur. Attention : le deroule- 
ment du texte affiche ne se fera que si la macro est executee en dehors de l'EDI. 

La methode gotoRange du curseur visible offre une autre possibilite, la zone cible 
etant indiquee par un curseur d'ecriture : 

cu rseu rVi si bl e . gotoRange (monCu rseu r , True) 

Deplacer le curseur visible 

Le curseur visible offre diverses methodes listees dans le tableau 8-18, qui permettent 
de le deplacer dans le document, de maniere tres similaire a un curseur d'ecriture. 

Tableau 8-18 Methodes de deplacement du curseur visible 





Signification 




Page 


Obtenir le numero de la page en cours. 


Integer 


jumpToFi rstPage 


Aller a la premiere page. 


Non significatif. 


jumpToLastPage 


Aller a la derniere page. 


Non significatif. 


jumpToPage(n) 


Aller a la page numero n (valeur Integer). 


Non significatif. 


jumpToNextPage 


Aller a la page suivante. 


True si Taction a pu etre realisee. 


jumpToPrevi ousPage 


Aller a la page precedente. 


True si Taction a pu etre realisee. 


j umpToEndOf Page 


Aller a la fin de la page en cours. 


Non significatif. 


jumpToStartOfPage 


Aller au debut de la page en cours. 


Non significatif. 


goRight(n, SEL) 


Deplacer de n caracteres a droite. 


True si Taction a pu etre realisee. 


goLeftCn, SEL) 


Deplacer de n caracteres a gauche. 


True si Taction a pu etre realisee. 


goDown(n, SEL) 


Deplacer de n caracteres vers le bas. 


True si Taction a pu etre realisee. 


goUpCn, SEL) 


Deplacer de n caracteres vers le haut. 


True si Taction a pu etre realisee. 


gotoStartCSEL) 


Deplacer au debut du texte entier. 


Pas de resultat. 


gotoEnd(SEL) 


Deplacer a la fin du texte entier. 


Pas de resultat. 


gotoRange(zone, SEL) 


Positionner le curseur sur une zone donnee. 


Pas de resultat. 


screenDown 


Aller a la page ecran suivante. 


True si Taction a pu etre realisee. 


screenUp 


Aller a la page ecran precedente. 


True si Taction a pu etre realisee. 



Manipuler les documents OpenOffice.org 

Troisieme partie 



Tableau 8-18 Methodes de deplacement du curseur visible (suite) 
Sign 



gotoEndOfLine(SEL) 


Aller en fin de ligne. 


Pas de resultat. 


gotoStartOfLine(SEL) 


Aller en debut de ligne. 


Pas de resultat. 


isAtStartOfLine 


Le curseur est-il en debut de ligne ? 


True si oui. 


isAtEndOfLine 


Le curseur est-il en fin de ligne ? 


True si oui. 



La page courante, le nombre de pages 

La numerotation des pages est continue sur l'ensemble du document. La propriete 
Page du curseur visible fournit le numero de la page dans laquelle il se trouve. Apres 
avoir deplace le curseur visible a la derniere page, cette propriete nous donnera le 
nombre total de pages. Notez que le document du Zip telechargeable ne contient que 
2 pages et n'est pas significatif. 



rem Code08-01.odt 
Option Explicit 



bibli : Sel ectionTexte Module 5 



Sub NombreDePagesDuDocumentO 
Dim monDocument As Object 
Dim CurseurVisible As Object 
monDocument = Thi sComponent 

CurseurVisible = monDocument. CurrentController.ViewCursor 

CurseurVisible. jumpToLastPage ' aller a la derniere page 

print CurseurVi si bl e . Page ' afficher le numero de la page actuelle 

Curseu rVi si bl e . jumpToPage(26) 

End Sub 



Definir des positions de tabulation 

Inserer une tabulation dans un texte consiste a aj outer le caractere dont la valeur 
decimale est 9, c'est-a-dire chr(9). 

Les positions de tabulations (les taquets) sont celles definies dans le style du para- 
graphe en cours, ou celles definies par defaut. Si vous souhaitez des taquets specifi- 
ques, vous avez deux solutions : 

• La plus simple et pratique est d'utiliser un style de paragraphe que vous avez 
defini dans votre document. 

• Lautre consiste a definir laborieusement par programmation les taquets du para- 
graphe en cours, comme dans la macro ci-apres. 
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rem Code08-03 . odt bibli : Tabulations Modulel 
Option Explicit 

Sub MettreTaquetsTabulationO 
Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object, Textel As String 
Dim Tab As String 

Dim Posit ionTaquet As New com. sun. star. style. TabStop 

Dim ListeTaquets(2) As Object ' prevoir trois taquets 
Tab = chr(9) ' caractere de tabulation 

With PositionTaquet ' definition des taquets 
.DecimalChar = Asc(",") 
.FillChar = Asc(" ") 
.Position = 2500 ' 25 mm ( 2,5 cm ) 
.Alignment = com. sun . star . styl e .TabAl ign . LEFT 
ListeTaquets(O) = PositionTaquet 
.Position = 4700 1 47 mm 

.Alignment = com. sun . star . styl e .TabAl ign . CENTER 
ListeTaquets(l) = PositionTaquet 

.Position = 7010 ' 70,1 mm 

.Alignment = com. sun. star. style. TabAl ign. RIGHT 
ListeTaquets(2) = PositionTaquet 

end With 



monDocument = Thi sComponent 

monTexte = monDocument .Text 

monCurseur = monTexte. createTextCursor 

monCurseur. gotoNextParagraph(false) 'sauter le titre 

' mettre les taquets sur le paragraphe en cours 

monCurseur . ParaTabStops = ListeTaquetsO 

' inserer un texte avec tabulations 

Textel = "Debut" & Tab & "TabO" & Tab & "Tabl" & Tab & "Tab2" 
monTexte. i nsertStri ng( monCurseur, Textel, false) 
End Sub 

Vous devez affecter tous les taquets en une seule fois, avec un tableau comportant le 
nombre de taquets necessaires. Chaque taquet est une structure composee de plu- 
sieurs valeurs indiquees au tableau 8-19. 



Tableau 8-19 Composantes d'un taquet 



Position 


Long 


La position du taquet par rapport a la marge gauche, en 1/100 de mm. 


Al i gnment 


Long 


Le type de tabulation, sous forme d'une constante, voir le tableau 8-20. 


DecimalChar 


Char 


Le caractere separateur decimal (en France, la virgule). 


FillChar 


Char 


Le caractere de suite, qui remplit les blancs, par exemple un pointille. 
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Le type Char, indique pour les elements Decimal Char et Fill Char, n'existe pas en 
Basic. On peut cependant remplir ces elements avec un nombre correspondant a la 
valeur ASCII du caractere. Ceci est realise avec la fonction Basic Asc(). 

La composante Alignment precise le type de tabulation. La valeur est une constante 
nommee (tableau 8-20) de la forme : 

com . sun . star . styl e . TabAl i gn . CENTER 

Tableau 8-20 Constantes d'alignement de tabulation 



Constante Position du taquet de tabulation 


LEFT 


A gauche du texte a tabuler. 


CENTER 


Au centre du texte a tabuler. 


RIGHT 


A droite du texte a tabuler. 


DECIMAL 


Sur le separateur de decimales. 


DEFAULT 


Position suivant la valeur par defaut. 



Rechercher - remplacer 

Les mecanismes de recherche dans un document Writer utilisent un objet 
« descripteur de recherche ». Nous allons l'utiliser dans un premier exemple qui con- 
siste a trouver dans le document toutes les occurrences d'un mot. Chaque mot trouve 
est ensuite mis en exergue avec un arriere-plan colore. 

rem Code08-04 . odt bibli : Rechercher Modulel 
Option Explicit 

Sub TrouverToutPartoutO 

Dim monDocument As Object 

Dim jeCherche As Object, trouv As Variant 

Dim x As Long 

monDocument = Thi sComponent 

jeCherche = monDocument . createSearchDescriptor 

with jeCherche 

.SearchString = "Marseille" 

.SearchWords = true 
end with 

trouv = monDocument. findAll (jeCherche) 

print "Nombre d'occurrences : " & trouv. Count 

for x = 0 to trouv. Count -1 

trouv(x) .CharBackColor = 1234567 ' fond vert sombre 
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next 
End Sub 

Un descripteur de recherche est obtenu avec la methode createSearchDescri ptor de 
l'objet document. Ce descripteur est une structure qui comporte plusieurs elements a 
remplir avant de lancer la recherche. L'objet document fournit la fonction f i ndAl 1 , qui 
a pour argument l'objet descripteur de recherche, et renvoie un objet conteneur conte- 
nant toutes les occurrences trouvees. Leur nombre est disponible dans la propriete 
Count de l'objet conteneur. Basic permet d'obtenir les occurrences par une simple 
indexation du conteneur ; ce sont des zones de texte, qui peuvent servir a effectuer des 
modifications simples ou a creer un curseur d'ecriture pour plus de possibilites. 

La structure Basic Wi th ... End Wi th evite de repeter le nom de la variable descrip- 
teur sur plusieurs lignes. Sans elle, on ecrirait : 

jeCherche. SearchStri ng = "Marseille" 
jeCherche. SearchWords = true 



Le descripteur de recherche 

Le tableau 8-21 liste les elements du descripteur. Leur utilisation est identique a la 
fonction de recherche de l'interface utilisateur. 



Limitation 

La recherche dans les notes du document, apparue dans l'interface utilisateur de la version 3.1 d'Open- 
Office.org, n'est pas encore disponible depuis I'API, voir Tissue 100557. 



Tableau 8-21 Descripteur de recherche 



SearchStri ng 


String 


La chame de caracteres a rechercher. 


SearchBackwards 


Boolean 


True pour faire une recherche a reculons (cela peut servir) ; par 
defaut, on recherche dans le sens normal de lecture. 


SearchCaseSensi ti ve 


Boolean 


True pour distinguer les majuscules des minuscules dans la 
recherche. Par defaut, il n'y a pas de distinction. 
Quelle que soit la valeur de cette propriete, les caracteres accen- 
tues sont toujours differences des caracteres non accentues. 


SearchWords 


Boolean 


True pour ne rechercher que des mots. Par defaut, on recherche la 
sequence de caractere n'importe oil. 


SearchRegularExpression 


Bool ean 


True pour faire une recherche avec la methode des expressions 
regulieres. Par defaut, on recherche une simple egalite de chame. 
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Tableau 8-21 Descripteur de recherche (suite) 



SearchStyl es 


Bool ean 


True pour rechercher des paragraphes d'un style donne par 
SearchStri ng ; par defaut, on cherche du texte. 


SearchSi mi 1 ari ty 


Bool ean 


True pour rechercher un texte similaire au texte cherche. 


SearchSi mi 1 ari tyRel ax 


Boolean 


True pour essayer toute combinaison des trois criteres suivants 
qui permettent de retrouver le texte cherche. 


SearchSi mi 1 ari tyRemove 


Integer 


Nombre de caracteres a retrancher pour retrouver le texte cherche. 


SearchSi mi 1 ari tyAdd 


Integer 


Nombre de caracteres a ajouter pour retrouver le texte cherche. 


SearchSi mi 1 ari tyExchange 


Integer 


Nombre de caracteres a changer pour retrouver le texte cherche. 


SearchAttributes 


ArrayO 


Tableau d'attributs a rechercher (voir explications dans la section 
suivante). 


Val ueSearch 


Boolean 


True si on recherche certaines valeurs des attributs (valeur par 
defaut). 

Fal se si on recherche seulement si certains attributs existent. 



Piece Norn du style recherche 

Pour rechercher un style, la propriete SearchStri ng doit contenir le nom localise du style, et non pas 
le nom anglais. Relisez a ce sujet la section « Appliquer un style a un paragraphe ». 



Rechercher des attributs particuliers 

La propriete SearchAttributes sert a limiter la recherche a certains formatages. 
Pour remplir chacune de ces proprietes, il faut constituer un tableau de 
PropertyVal ue et l'affecter a la propriete souhaitee. Dans 1'exemple suivant, nous 
recherchons les zones soulignees d'une ondulation. Le texte du document (voir le 
Zip telechargeable) contient plusieurs mots soulignes de differentes manieres. 

rem Code08-04 . odt bibli : Rechercher Module6 
Option Explicit 

Sub TrouverAttributsPartoutO 

Dim monDocument As Object 

Dim jeCherche As Object, trouv As Variant 

Dim x As Long 

monDocument = Thi sComponent 

Dim attRech(O) As New com. sun . star . beans . PropertyVal ue 
attRech(O) .Name = "CharUnderl ine" 

attRech (0) .Value = com. sun. star. awt . FontUnderl ine. WAVE 
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jeCherche = monDocument . createSearchDescri ptor 
jeCherche.SearchAttributes = attRech() 
jeCherche. ValueSearch = True 

trouv = monDocument . fi ndAl 1 (jeCherche) 

print "Nombre d ' occurrences : " & trouv. Count 

for x = 0 to trouv. Count -1 

trouv(x) .CharBackColor = 1234567 ' fond vert sombre 
next 
End Sub 

La propriete SearchStri ng est par defaut une chaine vide. Ceci nous permet de 
rechercher toute occurrence de texte. On aurait pu rechercher une chaine particuliere 
comportant le soulignement. La propriete ValueSearch vaut ici True. Elle indique 
qu'il faut rechercher la valeur des attributs. Ici, nous recherchons l'attribut 
CharUnderl i ne avec la valeur correspondant a une ondulation. Mettez Val ueSearch a 
Fal se et la macro trouvera tout type de soulignement. 

Limiter le champ de la recherche 

Si vous executez le premier exemple (macro TrouverToutPartout) sur le document 
fourni dans le Zip telechargeable, vous constaterez des effets genants : le document 
comporte un en-tete, un has de page, un tableau et, comme par hasard, ces zones 
contiennent aussi le mot recherche. Elles sont toutes modifiees par la macro, alors 
qu'en realite seul le texte principal nous interessait. 

Pour eviter ce desastre, nous allons verifier que chaque zone de texte trouvee est bien 
dans le texte principal. La fonction Basic Equal UnoObjects sera utilisee pour verifier 
que la propriete Text de la zone trouvee et la propriete Text du document indiquent 
bien le meme objet. 

rem Code08-04 . odt bibli : Rechercher Module2 
Option Explicit 

Sub TrouverToutdansleTexteO 
Dim monDocument As Object, monTexte As Object 
Dim jeCherche As Object, trouv As Variant 
Dim x As Long, posTrouve As Object 
monDocument = Thi sComponent 

monTexte = monDocument .Text ' objet = texte principal 
jeCherche = monDocument . createSearchDescri ptor 
with jeCherche 

. SearchStri ng = "Marseille" 

.SearchWords = true 
end with 

trouv = monDocument . fi ndAl 1 (jeCherche) 
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print "Nombre d'occurrences : " & trouv. Count 
for x = 0 to trouv. Count -1 
posTrouve = trouv (x) 

if Equal UnoObjects(monTexte, posTrouve. Text) then 

' L' occurrence est bien dans le texte principal 
posTrouve. CharBackColor = 1234567 ' fond vert sombre 
end if 

next 

End Sub 

Toutes les occurrences sont trouvees, mais seules celles du texte principal sont utilisees. 
Dans un cas plus general, on peut avoir besoin de savoir oil se trouve l'occurrence : dans 
le texte principal, dans un cadre, dans une cellule de tableau, dans un pied de page, etc. 
La methode est identique a celle exposee plus haut dans la section « Ou se trouve le 
curseur ? », en employant posTrouve aulieu de curseurVisible. 

Un autre moyen de recherche consiste a trouver la premiere occurrence avec la 
methode findFi rst de l'objet document, puis a rechercher les occurrences suivantes 
avec la methode findNext jusqu'a echec de la recherche. Void l'equivalent de 
l'exemple precedent, en utilisant cette technique. 

rem Code08-04 . odt bibli : Rechercher Module3 
Option Explicit 

Sub Rechercher Pa rtoutdansl eTexteO 

Dim monDocument As Object, monTexte As Object 

Dim jeCherche As Object, posTrouve As Object 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

jeCherche = monDocument . createSearchDescri ptor 
with jeCherche 

.SearchString = "Marseille" 

. Searchwords = true 
end with 

posTrouve = monDocument . findFi rst(jeCherche) 
Do Until isNull (posTrouve) 

if Equal UnoObjects (monTexte, posTrouve. Text) then 
' L'occurrence est bien dans le texte principal 
posTrouve. CharBackColor = 1234567 ' fond vert sombre 

end if 

posTrouve = monDocument. findNext (posTrouve. End, jeCherche) 
Loop 

End Sub 

Si la recherche ne trouve rien, l'objet posTrouve recoit la valeur Nul 1 et la boucle nest 
pas executee. 
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II est souvent necessaire de restreindre la recherche a une certaine zone de texte dans 
le document. Nous allons utiliser un curseur d'ecriture pour selectionner la zone de 
recherche dans le texte, puis nous allons verifier si la fin de la zone trouvee est encore 
dans la zone de recherche. La recherche debutera, non pas avec findFi rst, mais avec 
f i ndNext qui nous permet d'imposer le point de depart de la recherche. 

rem Code08-04 . odt bibli : Rechercher Module4 
Option Explicit 

Sub Recherche rDans Parti eDeTexteO 

Dim monDocument As Object, monTexte As Object 

Dim jeCherche As Object, posTrouve As Object 

Dim monCurseur As Object 

monDocument = Thi sComponent 

monTexte = monDocument .Text 

monCurseur= monTexte . createTextCursor 

monCurseur. gotoNextParagraph(fal se) ' debut du 2eme paragr 
monCurseur .gotoNextParagraph (true) ' selection du 2eme paragr 
jeCherche = monDocument . createSearchDescri ptor 
with jeCherche 

.SearchString = "et" 

.SearchWords = true 
end with 

posTrouve = monDocument. findNext(monCurseur. Start, jeCherche) 

Do Until i sNull (posTrouve) 

if EqualUnoObjects(monTexte, posTrouve. Text) then 
if monTexte. compareRegionEnds( 

posTrouve, monCurseur) < 0 then Exit Do 

' L'occurrence est dans la zone de recherche 
posTrouve. CharBackColor = 1234567 ' fond vert sombre 
end if 

posTrouve = monDocument . fi ndNext (posTrouve . End , jeCherche) 
Loop 
End Sub 

La fonction compareRegionEnds renvoie -1 si la zone en premier argument com- 
mence apres la zone en deuxieme argument. Dans ce cas, Exi t Do termine immedia- 
tement la boucle. 

La zone de recherche pourrait etre une zone selectionnee par l'utilisateur ; comme 
nous l'avons decrit plus haut. 

II est possible de selectionner visuellement la zone trouvee, au lieu de changer la cou- 
leur de fond : 

monDocument . Cu r rentCont rol 1 e r . Sel ect (posTrouve) 
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Rechercher pour remplacer 

Lors d'une recherche, la zone de texte posTrouve selectionne le texte trouve. Nous 
pouvons utiliser cette zone de texte pour creer un curseur d'ecriture et modifier le 
texte a notre guise. En reprenant l'exemple precedent, nous allons maintenant rem- 
placer les mots « et » de la zone selectionnee par le caractere « & ». De plus, si la zone 
trouvee est « Et », nous changerons la taille de caractere. 

rem Code08-04 . odt bibli : Rechercher Module5 
Option Explicit 

Sub Rempl acerDansParti eDeTexteO 

Dim monDocument As Object, monTexte As Object 

Dim jeCherche As Object, posTrouve As Object 

Dim monCurseur As Object, Curseur2 As Object 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

monCurseur= monTexte . createTextCursor 

monCurseur. gotoNextParagraph(false) 'debut du 2eme paragr 
monCurseur. gotoNextParagraph(true) ' selection du 2eme paragr 
jeCherche = monDocument . createSearchDescri ptor 
with jeCherche 

. SearchStri ng = "et" 

. SearchWords = true 
end with 

posTrouve = monDocument. findNext(monCurseur. Start, jeCherche) 
Do Until i sNul 1 (posTrouve) 

if Equal UnoObjects (monTexte, posTrouve. Text) then 
if monTexte. compareRegionEnds(_ 

posTrouve, monCurseur)< 0 then Exit Do 
' L'occurrence est dans la zone de recherche 
Curseur2 = monTexte. createTextCursorByRange(posTrouve) 
' Curseur2 selectionne le texte trouve 
if Curseur2 .String = "Et" then Curseur2 .Char Height = 16 
Curseur2 .String = "&" ' changer le texte 
end if 

posTrouve = monDocument . fi ndNext(posTrouve . End , jeCherche) 
Loop 
End Sub 

La propriete String de l'objet Curseur2 contient initialement le texte trouve. En 
changeant sa valeur, nous remplacons le texte existant par un autre. Nous aurions 
aussi bien pu deplacer le curseur et effectuer toute sorte de remplacement, insertion, 
suppression sur les textes trouves. 
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Tout remplacer 

Dans le cas simple ou toutes les occurrences doivent etre systematiquement rempla- 
cees partout, texte principal et autres textes, l'objet document offre la fonction 
repl aceAl 1 , qui effectue ce travail et renvoie le nombre de remplacements. Elle uti- 
lise un descripteur de remplacement qui contient tous les elements du descripteur de 
recherche et d'autres listes dans le tableau 8-22. 



Tableau 8-22 Descripteur de remplacement (elements specifiques) 





ReplaceString 


Stri ng 


La chame de caracteres a mettre a la place de celle trouvee. 


Repl aceAttri butes 


ArrayQ 


Tableau d'attributs de remplacement (voir explications). 



On utilise une nouvelle methode createReplaceDescriptor pour obtenir un des- 
cripteur de remplacement. Pour un simple remplacement de texte, il suffit de remplir 
en plus Repl aceStri ng. 



rem Code08-04 . odt bibli : Remplacer Modulel 
Option Explicit 

Sub RemplacerTextePartoutO 

Dim monDocument As Object 

Dim jeCherche As Object, nbrFois As Long 

monDocument = Thi sComponent 

jeCherche = monDocument. createReplaceDescriptor 

with jeCherche 

.SearchString = "Marseille" 
.ReplaceString = "Bordeaux" 

. SearchWords = true 
end with 

nbrFois = monDocument. repl aceAll (jeCherche) 
print "Nombre de remplacements : " & nbrFois 

End Sub 

Rappelons que repl aceAl 1 ne permet pas de distinguer le texte principal des autres 
textes du document. 

La macro suivante modifie tous les paragraphes de style Styl el, pour leur affecter un 
autre style Style2. Si Styl el est specifique au type de texte considere dans le docu- 
ment (par exemple utilise seulement dans le texte principal), il n'y aura pas d'effet 
pervers. Attention, utilisez le nom anglais du style s'il est predefini par Open- 
Office. org (voir la section sur les styles). 
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rem Code08-04 . odt bibli : Remplacer Module2 
Option Explicit 

Sub RemplacerStylePartoutO 
Dim MonDocument As Object 
Dim DeCherche As Object 
Dim MonCurseur As Object 
MonDocument = Thi sComponent 

DeCherche = MonDocument . createRepl aceDescri ptor 
with JeCherche 

.SearchString = "Stylel" 

.ReplaceString = "Style2" 

.SearchStyles = true 
end with 

MonDocument. replaceAll (JeCherche) 
End Sub 

Nous avons vu que la propriete SearchAttri butes sert a limiter la recherche a cer- 
tains formatages. La propriete ReplaceAttri butes precise les formatages a appliquer 
sur les zones trouvees. II est possible d'utiliser l'une ou l'autre de ces proprietes, les 
deux, ou aucune. 

Dans l'exemple suivant, nous recherchons les mots « ses » qui sont soulignes d'une 
ondulation. Nous allons conserver le texte, mais lui imposer le formatage : sans 
ondulation, italique, gras et avec un fond vert. Le texte du document (voir le Zip 
telechargeable) contient plusieurs mots « ses », mais un seul est souligne en ondule. 

rem Code08-04 . odt bibli : Remplacer Module3 
Option Explicit 

Sub Rempl acerAttri buts() 
Dim MonDocument As Object 
Dim JeCherche As Object 
Dim MonCurseur As Object 

Dim attRech(O) As New com. sun. star .beans. PropertyVal ue 
Dim attRempl(3) As New com. sun. star. beans. PropertyVal ue 

attRech(O) .Name = "CharUnderl ine" 

attRech(O) .Value = com. sun . star . awt . FontUnderl i ne .WAVE 
attRempl (0) .Name = "CharPosture" 

attRempl (0) .Val ue = com . sun . star . awt . FontSl ant . ITALIC 
attRempl (1) .Name = "CharUnderl ine" 

attRempl (1) .Val ue = com . sun . star . awt . FontUnderl i ne . NONE 
attRempl (2) . Name = "CharWeight" 

attRempl (2) .Val ue = com . sun . star . awt . FontWeight . BOLD 
attRempl (3) . Name = "CharBackColor" 

attRempl (3) .Val ue = 1234567 ' fond vert sombre 
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MonDocument = Thi sComponent 

JeCherche = MonDocument . createRepl aceDescri ptor 
with JeCherche 

.SearchString = "ses" 

. Repl aceStri ng = "ses" ' on ne change pas le texte 
. SearchWords = true 
.Val ueSearch = True 
.SearchAttributes = attRechO 
.ReplaceAttributes = attRempl C) 
end with 

MonDocument. replaceAll (JeCherche) 
End Sub 

Si on donne a la propriete Val ueSearch la valeur Fal se, tout formatage de souligne- 
ment est recherche, et la valeur est ignoree. Dans ce cas, le remplacement d'attributs 
ne fonctionne pas, il est seulement possible de modifier le texte. Vous pouvez faire 
l'essai en modifiant deux lignes sur l'exemple precedent : 

I.ReplaceString = "mes" ' on change le texte 
.ValueSearch = False' recherche de 1 'existence d'attributs 



Rechercher des paragraphes 

II est facile de parcourir un texte paragraphe par paragraphe. Dans cet extrait de 
code, nous recherchons dans un texte les paragraphes d'un style donne. 

Dim listePargr As Object, elmt As Object 

listePargr = leDocument.Text.createEnumeration 
Do While listePargr.hasMoreElements 
elmt = listePargr.nextElement 

if el mt.supportsService("com. sun. star. text. Paragraph") Then 
Select Case elmt .paraStyleName 

Case "TitreNi veaul" 

' faire quelque chose 
Case "TitreNiveau2" 

print elmt. String 1 visualiser le contenu du paragraphe 
Case "TitreNiveau3" 

' faire autre chose 
end select 
end if 
Loop 

Nous obtenons de l'objet texte un enumerateur de paragraphes. Les tableaux etant 
compris dans cette liste, nous les eliminons en verifiant si l'element trouve supporte 
le service de paragraphe. 
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Attention a la casse ! Les noms de services doivent etre ecrits en respectant les 
majuscules et minuscules. 

La propriete paraStyl eName nous donne le style du paragraphe, que nous pouvons 
modifier par simple affectation. La propriete Stri ng d'un paragraphe renvoie le texte 
qu'il contient (avec un petit risque qu'il soit tronque). On peut ensuite affecter un 
autre texte a cette propriete. 

Les tableaux 

Creer et manipuler un tableau Writer entierement par programmation nest pas une 
mince affaire, vous allez le voir. Ici encore, vous avez interet a partir d'un document exis- 
tant, avec le ou les tableaux necessaires, formates manuellement a votre convenance. Avec 
une macro, il suffit alors de retrouver chaque tableau grace a son nom et de le remplir. 

Inserer un tableau 

On utilise un curseur pour designer l'endroit d'insertion du tableau. La methode 
createlnstance de l'objet document fournit l'objet tableau. II est ainsi repertorie 
dans l'ensemble des tableaux du document. La methode initialize de l'objet 
tableau specifie le nombre de lignes et de colonnes. Linsertion effective du tableau 
sera faite par la methode i nsertTextContent de l'objet texte. 

rem Code08-05 . odt bibli : AjoutTableau Modulel 
Option Explicit 

Sub InsererUnTableauO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object, maTable As Object 
monDocument = Thi sComponent 
monTexte = monDocument. Text 
monCurseur = monTexte. createTextCursor 
monCurseur .gotoNext Paragraph (Fal se) 
monCurseur .gotoNextParagraph(Fal se) 

maTabl e = monDocument . createInstance("com . sun . star . text . TextTabl e") 
maTable. initialized, 9) ' nombre de : lignes, colonnes 
monTexte. insertTextContentCmonCurseur, maTable, false) 

End Sub 

Largument de createlnstance doit etre ecrit en respectant la casse. 
Le troisieme argument de la methode i nsertTextContent signifie : 

• Fal se = inserer dans le texte ; 

• True = ecraser la zone actuellement selectionnee par le curseur. 
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Inserer plusieurs tableaux 

A chaque insertion d'un tableau, il est necessaire d'obtenir un nouvel objet 
TextTabl e, comme dans cet exemple. 

rem Code08-05 . odt bibli : AjoutTableau Module2 
Option Explicit 

Sub InsererPlusieursTableauxO 

Dim monDocument As Object, monTexte As Object 

Dim monCurseur As Object, maTable As Object 

monDocument = Thi sComponent 

monTexte = monDocument .Text 

monCurseur = monTexte. createTextCursor 

monCu rseu r . gotoNextParag raph (Fal se) 

monCu rseu r . gotoNextParag raph (Fal se) 

maTable = monDocument. createInstance("com. sun. star. text. TextTable") 

maTabl e . i ni ti al i ze(5 , 9) ' nombre de : lignes, colonnes 

monTexte. insertTextContent(monCurseur, maTable, false) 

' - - - ( remplir le premier tableau ) - - - 

monCurseur. gotoNextParagraph(False) ' aller ailleurs 

maTabl e = monDocument . createInstance("com . sun . star . text . TextTabl e") 

maTable. initial ize(2 ,6) ' nombre de : lignes, colonnes 

monTexte. insertTextContent(monCurseur, maTable, false) 

End Sub 



Trouver un tableau existant 

Rappelons que tout tableau possede un nom (par defaut, en version francaise : 
Tableaul, Tableau2, etc. par ordre de creation). Avec le Navigateur, on peut donner 
un nom plus specifique a chaque tableau. 

Supposons que dans un document existant nous ayons a modifier le contenu d'un 
tableau nomme « Finances ». L'objet document fournit la collection de ses tableaux 
avec la propriete TextTabl es (notez le s du pluriel). On obtient un tableau d'un nom 
particulier avec la methode getByName de l'objet collection. On peut aussi acceder a 
un tableau par son numero d'ordre avec la methode getBylndex. Avec OOoBasic, le 
getBylndex peut etre omis, comme si on indexait une variable tableau. 

' acces par index 

maTable = monDocument. TextTabl es.getByIndex(2) 

maTable = monDocument. TextTables(2) ' simplification Basic 

' acces par le nom 

maTable = monDocument. TextTabl es.getByName(" Finances") 
Nous pouvons maintenant modifier le tableau en utilisant la variable maTabl e. 
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Le getByName declenchera une exception s'il n'existe aucun tableau de ce nom. Vous 
pouvez verifier qu'un tel nom de tableau existe bien : 

"if monDocument .TextTabl es . hasByName("Fi nances") then 

' le tableau existe, le modifier 
end if 

II est facile de renommer un tableau avec sa propriete Name. Notons qu'un nom de 
tableau ne doit pas comporter de caractere espace. 

maTable = monDocument .TextTabl es . getByName("Fi nances") 
maTabl e . Name = "Fi nances_2003" 

L'objet TextTabl es nous permet de connaitre tous les tableaux du document et done 
de les modifier. Le nombre de tableaux est fourni par la propriete Count, leurs noms 
sont obtenus avec la propriete Name de chaque objet tableau. 

rem Code08-05 . odt bibli : AjoutTableau Module3 
Option Explicit 

Sub Li sterLesTabl eaux() 

Dim monDocument As Object 

Dim lesTables As Object, maTable As Object 

Dim x As Long 

monDocument = Thi sComponent 
lesTables = monDocument. TextTabl es 
for x = 0 to lesTables. Count -1 
maTable = lesTables(x) 

print "Tableau : " & maTable. Name 
next 
End Sub 

Attention, l'ordre des tableaux dans la liste de TextTabl es ne correspond pas force- 
ment a l'ordre dans le document. 

Supprimer un tableau 

Avec une variable maTabl e pointant sur un tableau, on supprime celui-ci en utilisant 
la methode removeTextContent de l'objet texte. 

if MsgBox("Effacer ce tableau ?", 132) = 6 then 

monTexte . removeTextContent (maTabl e) 
end if 
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Proprietes de tableau 

Le tableau 8-23 liste les principales proprietes de tableau. Les valeurs par defaut se 
reglent depuis le menu Outils>Options>OpenOffice.org Writer>Table. 

Tableau 8-23 Proprietes de tableau 



Name 


Stri ng 


Nom du tableau. 


BreakType 


Integer 


Impose un saut de page ou de colonne avant ou apres le tableau. 
Memes valeurs que pour le texte principal, voir le tableau 8-4. 


KeepTogether 


Boolean 


True pour maintenir ce tableau et le paragraphe suivant sur la meme 
page ou la meme colonne. 


Spl i t 


Boolean 


Fal se : impose que le tableau ne soit pas a cheval sur deux pages ou 
deux colonnes (a condition que le tableau tienne dans la page !) 

"T" lj_LI J. ' ' J. 1 _ 1 1 

True : le tableau peut s etendre sur deux pages ou plus. 


PageDescName 


String 


Si cette propriete contient un nom de style de page, un saut de page est 
effectue avant le tableau et la nouvelle page prend ce style. 


PageNumbe rOf f set 


Intege r 


Premier numero de page s'il y a eu un saut de page force. 


RepeatHeadl i ne 


Bool ean 


True pour repeter I'en-tete a chaque nouvelle page. 


Heade rRowCount 


Long 


Nombre de lignes de I'en-tete. 


TopMargi n 


Long 


Marge entre le haut du tableau et le paragraphe precedent, en 1 /1 00 
de mm. 


BottomMargi n 


Long 


Marge entre le bas du tableau et le paragraphe suivant, en 1/100 
de mm. 


LeftMargi n 


Long 


Marge de gauche du tableau, voir la section « Largeur du tableau ». 


RightMargin 


Long 


Marge de droite du tableau, voir la section « Largeur du tableau ». 


Shadow/Format 


Object 


Ombre du tableau, voir le tableau 8-9 et ses explications. 


BackTransparent 


Boolean 


True rend le fond transparent (interface utilisateur : sans remplissage). 


BackColor 


Long 


Couleur du fond. 


Tab! eCol umnSeparators 


Object 


Decrit plus loin, a la section « Colonnes ». 


Tab! eCol umnRel ati veSum 


Integer 


Lecture seulement. Decrit plus loin, a la section « Colonnes ». 


Tab! eBorder 


Object 


Bordures du tableau, voir la section « Bordures de tableau ». 


CollapsingBorders 


Boolean 


Bordures : True pour fusionner les styles de lignes adjacents. 



Pour un nouveau tableau, ces proprietes peuvent etre modifiees avant ou apres l'ins- 
truction initialize, mais toujours apres createlnstance. 
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Bordures de tableau 

Referez-vous a l'onglet Bordures du panneau Format de tableau (figure 8-1). Sur ce 
panneau, les largeurs de trait sont indiquees en point typographique pica. 



Precision 

Un point pica vaut 35,28 centiemes de millimetres. 



Figure 8-1 

L'onglet bordures 
du Format de tableau 



Format de tableau 



Tableau | Enchainements | Colonnes Bordures | Arriere-plan 

Disposition des lignes 
Par defaut 

rniBiffliEB 

Defini par I'utilisateur 



Style d'ombre 
Position 



Espacement avec le contenu — 
|o,lOcrn 7] 



PQrrr 

Proprietes — 
I - £usionner les styles de ligne adjacents 




Les bordures de tableau sont exposees par la propriete TableBorder. Cette derniere 
est une structure (voir le tableau 8-24) dont chaque descripteur de ligne (TopLine, 
LeftLine, etc.) est lui-meme une structure de bordure deja decrite au tableau 8-8. 



Tableau 8-24 Structure de TableBorder 



IsTopLineValid 


Boolean 


Validation de la bordure du haut, voir texte. 


TopLi ne 


Object 


Structure de la ligne de bordure du haut. Voir le tableau 8-8. 


IsBottomLi neVal i d 


Boolean 


Validation de la bordure du bas, voir texte. 


BottomLi ne 


Object 


Structure de la ligne de bordure du bas. Voir le tableau 8-8. 


IsLeftLineValid 


Boolean 


Validation de la bordure gauche, voir texte. 


LeftLi ne 


Object 


Structure de la ligne de bordure gauche. Voir le tableau 8-8. 


IsRightLineValid 


Boolean 


Validation de la bordure droite, voir texte. 
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Tableau 8-24 Structure de TableBorder (suite) 



Element 


Type 


Signification 


Ri ghtLi ne 


Object 


Structure de la ligne de bordure droite. Voir le tableau 8-8. 


IsHori zontal Li neVal i d 


Boolean 


Validation des lignes horizontales interieures, voir texte. 


Hon' zontal Li ne 


Object 


Structure des lignes horizontales interieures. Voir le tableau 8-8. 


IsVe rti cal Li neVal i d 


Boolean 


Validation des lignes verticales interieures, voir texte. 


Vertical Line 


Object 


Structure des lignes verticales interieures. Voir le tableau 8-8. 


IsDi stanceVal i d 


Bool ean 


True si I'ecart avec le contenu est utilise. 


Di stance 


Integer 


Ecart avec le contenu, en 1/1 00 de mm, pour toutes les bordures. 



Le reglage d'un ecart avec le contenu different suivant les bordures ne semble ni rea- 
lisable ni visible a travers l'API. La propriete Distance correspond a I'ecart 
« synchronise » du panneau d'interface utilisateur. 

Les proprietes Is . . . Val id ont une signification subtile : 

• En lecture, un tel indicateur precise True si la structure Line correspondante est 
valable sur toute la longueur de la ligne. II indique Fal se si la structure de la ligne 
varie le long des cellules qui la constituent. 

• En ecriture, la signification est totalement differente : employez la valeur True 
pour modifier la structure Li ne correspondante, et employez la valeur Fal se pour 
garder la valeur actuelle de la structure Li ne correspondante. Dans l'affectation de 
la nouvelle valeur de TableBorder, la structure Line correspondante ne sera done 
pas prise en compte. 

Modifier une bordure necessite d'utiliser des variables intermediaires pour acceder 
aux structures : 

Dim lesBords As Object 

Dim unBord As New com. sun. star .table. Border Line 

lesBords = maTable. TableBorder 
unBord.OuterLineWidth = 250 ' 2 , 5 mm 
unBord. Color = RCB(200,0,0) ' rouge 

1 esBords . IsLeftLineVal id = True ' forcer le changement de bordure 
lesBords. LeftLine= unBord ' changer la bordure gauche 
maTable. TableBorder = lesBords 

La variable lesBords recupere l'etat actuel des bordures. La variable unBord est 
declaree par Dim comme une structure BorderLine vierge, puis reglee aux valeurs 
desirees. On aurait pu recuperer le contenu de Lef tLi ne dans la variable unBord, et la 
modifier. II ne faut pas oublier de mettre a True la propriete Is. . .Valid correspon- 
dant a la bordure a modifier, sinon le resultat dependra de sa valeur actuelle dans la 
variable lesBords. 
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Les proprieties IsHorizontalLineValid et IsVerticalLineValid traitent toutes les 
lignes du quadrillage interieur. 

• En lecture, la valeur True indique que toutes les lignes de ce type ont les memes 
valeurs de bordure. 

• En ecriture, la valeur True indique que toutes les lignes de ce type doivent prendre 
la meme valeur de bordure. 

Supprimer des bordures dans un tableau 

II ressort des explications precedentes que, pour supprimer une bordure, il faut 
mettre a True l'indicateur Is . . . LineVal id, et mettre les elements InnerLineWidth et 
OuterLineWidth de la structure BorderLine correspondante a zero. Void un moyen 
plus simple : 

Dim bordures As New com. sun. star. table. TableBorder 
bordures . IsTopLi neVal id = True 
bordures . IsVerti cal Li neVal i d = True 
maTable. TableBorder = bordures 

On cree une structure TableBorder vierge, avec tous ses elements a zero, et on met a 
True les indicateurs de validite des lignes a effacer (ici la ligne du haut et les lignes 
interieures verticales). 

Ombre de tableau 

Nous avons deja decrit l'objet Shadow/Format dans le cadre des paragraphes (voir le 
tableau 8-9). L'utilisation est tres similaire, le document Code08-05 .odt du Zip tele- 
chargeable montre un exemple. Attention, dans certaines versions d'OpenOffice.org 
l'ombre n'est pas affichee par Writer (voir Tissue 100641). 

Largeur du tableau 

II existe plusieurs proprietes interdependantes qui modifient la largeur d'un tableau. 
Positionnement horizontal 

La propriete Hori Orient, du type Integer, definit comment le tableau est positionne 
horizontalement, par rapport aux marges. Elle contient une constante nommee dont 
les valeurs possibles sont indiquees dans le tableau 8-25. La valeur par defaut est : 

com . sun . star . text . HoriOri entati on . FULL 

Comme la valeur par defaut est FULL, il est absolument necessaire de mettre une 
autre valeur (autre que NONE) pour pouvoir imposer une largeur. 
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Tableau 8-25 Constantes de positionnement horizontal de tableau 



Constante 


Signification 


NONE 


Etaler le tableau de la marge de gauche a la marge de droite. 


RIGHT 


Aligner le tableau sur la marge de droite. 


LEFT 


Aligner le tableau sur la marge de gauche. 


CENTER 


Centrer le tableau par rapport a I'espace disponible. 


FULL 


Etaler le tableau sur tout I'espace disponible, sans marges de table. 


LEFT_AND_WIDTH 


Aligner le tableau sur la marge de gauche, avec une largeur imposee 
par la propriete WIDTH 



La largeur se regie avec differentes proprieties indiquees dans le tableau 8-26. 
Tableau 8-26 Proprietes de reglage de largeur de tableau 



Propriete 



IsWidthRelative 


Boolean 


True : prendre en compte Rel ati veWi dth. 
Fal se : prendre en compte Wi dth. 


RelativeWidth 


Integer 


Valeur entre 1 et 100 : largeur en pourcentage de I'espace libre 
entre marges de gauche et de droite. 


Width 


Long 


Largeur absolue du tableau. L'unite de mesure n'est pas disponible. 


LeftMargi n 


Long 


Largeur absolue entre la marge gauche et le tableau, 
en 1/100 de mm. 


Ri ghtMargi n 


Long 


Largeur absolue entre la marge droite et le tableau, 
en 1/100 de mm. 



Applications pratiques 

Dans ces extraits de code, nous indiquons seulement les instructions concernant la 
largeur. Un exemple complet est disponible dans le Zip telechargeable, fichier 
Code08-05 .odt, bibliotheque ConfigTableau, module Module2. 

Les largeurs absolues dependent de diverses conditions (selon la documentation de 
l'API), aussi faites des essais avec vos documents pour determiner i'echelle. 
1 Tableau centre, largeur 80 % 

maTabl e . HoriOri ent = com . sun . star . text . HoriOri entati on . CENTER 
maTabl e. IsWidthRelative = true 
maTable. RelativeWidth = 80 



Les colonnes sont de largeurs inegales. Les proprietes LeftMargi n et Ri ghtMargi n 
sont ignorees. 
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2 Tableau centre, largeur absolue 

maTable. HoriOrient = com . sun . star . text . HoriOri entati on .CENTER 
maTable. IsWidthRelative = false 
maTable. Width = 8000 

La largeur obtenue est 141,1mm. Les proprietes LeftMargin et RightMargin 
sont ignorees. 

3 Tableau aligne a gauche, largeur 80 % 

maTabl e . HoriOri ent = com . sun . star . text .HoriOri entati on . LEFT_AND_WIDTH 
maTable. IsWidthRelative = true 
maTabl e.RelativeWidth = 80 
maTable. LeftMargin = 2000 ' 20 mm 

Les colonnes sont de largeurs inegales. La propriete Ri ghtMargi n est ignoree. 

4 Tableau aligne a gauche, largeur absolue 

maTabl e . Hori Ori ent = com . sun . star . text . Hori Ori entati on . LEFT_AND_WIDTH 

maTable. IsWidthRelative = false 

maTable. Width = 4000 

maTable. LeftMargin = 1000 ' 10 mm 

La largeur obtenue est 70,6 mm. La propriete RightMargin est ignoree en orien- 
tation L E FT_AN D_WI DTH . 

5 Tableau etale entre les marges gauche et droite 

maTable. HoriOrient = com . sun . star . text . HoriOri entati on . NONE 
maTable. LeftMargin = 2000 1 20 mm 
maTable. RightMargin = 3500 ' 15 mm 

Les proprietes IsWidthRelative, Relati veWidth, Width, sont ignorees. 

Lignes 

Certains objets ou proprietes decrits ici ne sont utilisables que sur un tableau cons- 
titue d'un quadrillage simple. 

Lobjet tableau fournit l'ensemble de ses lignes dans la propriete Rows, qui renvoie un 
objet conteneur. On accede a chaque ligne avec la methode getBylndex ayant pour 
argument son numero d'ordre (ligne zero pour la premiere ligne). Basic permet un 
acces direct par indexation, comme pour un Array. Le nombre de lignes du tableau 
est la propriete Count de l'objet Rows du tableau. 
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Les principales proprietes d'un objet ligne sont dans le tableau 8-27. 

Tableau 8-27 Proprietes d'une ligne de tableau 



IsAutoHeight 


Boolean 


True : la hauteur est adaptee au contenu de la ligne 
(valeur par defaut). 

Fal se : la hauteur depend de la propriete Hei ght. 


Height 


Long 


Hauteur de la ligne, en 1 /1 00 de mm. 


BackColor 


Long 


Couleur du fond. 


BackTransparent 


Long 


True rend le fond transparent (interface utilisateur : sans 
remplissage). 


Tabl eCol umnSeparators 


Object 


Acces aux separateurs de colonnes de la ligne (voir la 
description des colonnes). 



Exemple 



rem Code08-05 . odt 
Option Explicit 



bibli : LigneColonne Modulel 



Sub Modi fi erLi gne() 

Dim monDocument As Object, maTable As Object 
Dim lesLignes As Object, maLigne As Object 

monDocument = Thi sComponent 

maTable = monDocument. TextTables.getByName("Finances") 

lesLignes = maTable. Rows 

print "Nombre de lignes", lesLignes. Count 

maLigne= lesLignes(2) ' troisieme ligne 

With maLigne 

.Height = 1000 ' 10 mm 

.IsAutoHeight = False' prendre en compte Height 

.BackColor = RCB(240, 240, 0)' couleur jaune 
End With 
End Sub 

Les lignes sont numerotees a partir de zero. Nous allons ajouter 3 lignes groupees, dont 
la premiere aura le rang 2, en utilisant la methode i nsertBylndex de 1' objet Rows. 



rem Code08-05 . odt 
Option Explicit 



bibli : LigneColonne Module2 



Sub InsererLignesO 

Dim monDocument As Object, maTable As Object 
Dim lesLignes As Object, maLigne As Object 
monDocument = Thi sComponent 
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maTable = monDocument .TextTabl es . getByName("Fi nances") 
lesLignes = maTabl e . Rows 

lesLignes.insertByIndex(2,3) ' ajouter 3 lignes en position 2 
print "Maintenant on va supprimer" 

lesLignes.removeByIndex(2,3) ' supprimer ces trois "lignes 
End Sub 

L'ancienne ligne de rang 2 est maintenant la ligne de rang 5. 

Nous avons ensuite utilise une methode symetrique, removeBylndex, dontle premier 
argument est le rang de la premiere ligne a supprimer et le second contient le nombre 
de lignes a supprimer. 

Colonnes 

L'objet tableau fournit l'ensemble de ses lignes dans la propriete Columns, qui renvoie 
un objet conteneur. Mais il nest pas possible pour autant d'obtenir un objet colonne. Si 
vous souhaitez modifier toute une colonne, il faudra acceder a chacune de ses cellules. 
Le nombre de colonnes du tableau est la propriete Count de l'objet Col umns du tableau. 

L'objet TableColumnSeparators est defini pour un tableau si toutes les lignes ont la 
meme structure. II en existe aussi un par ligne de tableau. Cet objet liste les separa- 
teurs de colonnes. Chacun est une structure composee de deux elements, selon le 
tableau 8-28. Si le tableau possede 4 colonnes, il y a 3 separateurs, de rang 0 a 2. 

Tableau 8-28 Structure de TableColumnSeparators 



Element Type Signification 


Position 


Integer 


Position du separateur, par rapport au cote gauche du tableau. 


IsVisible 


Bool ean 


True si le separateur est visible. 



La propriete TableColumnRelativeSum, qui existe pour le tableau mais pas pour une 
ligne, est initialisee a une certaine valeur qui represente la largeur totale (ce nest pas 
une dimension). Les positions ont une valeur inferieure a celle-la. En clair, une posi- 
tion est caracterisee comme une proportion de la valeur maximale possible. En chan- 
geant la position d'un separateur, on modifie la largeur des deux colonnes adjacentes. 
Notez qu'on ne peut deplacer un separateur non visible. 

Dans cet exemple, nous affichons les valeurs de ces proprietes pour le tableau 
Resultats, puis nous modifions la position de deux separateurs. La macro montre 
comment definir une position de separateur comme une fraction de la largeur de la 
table. Notez l'usage du Variant et la maniere de mettre a jour l'objet 
TableCol umnSeparators. 
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rem Code08-05 . odt bibli : Li gneCol onne Module3 
Option Explicit 

Sub ChangerLargeurDeColonne() 

Dim monDocument As Object, maTable As Object 

Dim lesSep As Variant, lesColonnes As Object 

Dim largeur As Double 

monDocument = Thi sComponent 

maTable = monDocument. TextTabl es . getByName("Resul tats") 

largeur = MaTable. TableColumnRelativeSum 

lesColonnes = maTabl e . Col umns 

lesSep = maTabl e.TableColumnSeparators 

print "Nombre de colonnes : ", 1 esColonnes .Count 

print "Avant : ", largeur, _ 

lesSep(O) .Position, 1 esSep(l) . Posi ti on , lesSep(2) . Position 
lesSep(O) .Position = largeur * 0.1 
lesSep(2) .Position = largeur * 0.675 
maTabl e.TableColumnSeparators = lesSep 
print "Apres : ", largeur, _ 

lesSep(O) .Position, 1 esSep(l) . Posi ti on , lesSep(2) . Position 
End Sub 

Les colonnes sont numerotees a partir de zero. Nous allons ajouter 3 colonnes grou- 
pees, dont la premiere aura le rang 1, en utilisant la methode insertBylndex de 
l'objet Col umns. 

rem Code08-05 . odt bibli : LigneColonne Module4 
Option Explicit 

Sub InsererCol onnes () 

Dim monDocument As Object, maTable As Object 
Dim lesSep As Variant, lesColonnes As Object 
monDocument = Thi sComponent 

maTable = monDocument. TextTabl es . getByName("Resul tats") 
lesColonnes = maTabl e . Col umns 

lesColonnes. insertBylndexCl, 3) ' ajouter 3 colonnes au rang 1 
print "Maintenant on va supprimer" 

lesColonnes. removeByIndex(l, 3) ' supprimer ces trois colonnes 
End Sub 

L'ancienne colonne de rang 1 a ete decoupee en 4 colonnes, en gardant une largeur 
totale identique ; l'ancienne colonne de rang 1 est maintenant la colonne de rang 4. 

Nous avons ensuite utilise une methode symetrique, removeBylndex, dont le premier 
argument est le rang de la premiere colonne a supprimer et le deuxieme argument est 
le nombre de colonnes a supprimer. 
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Trouver une cellule ou une zone de cellules 

Les cellules d'un tableau Writer sont reperees par une adresse alphanumerique du 
genre B7, comme dans une feuille de classeur Calc. On obtient ainsi l'objet cellule de 
l'emplacement B7 : 

Dim maCellule As Object 

maCellule = maTabl e . getCell ByName("B7") 

Une cellule est aussi reperable par ses coordonnees de rang de colonne et de rang de 
ligne, que nous designerons par X et Y respectivement. Chaque rang est numerate a 
partir de zero. La meme cellule B7 peut alors etre obtenue par : 

Dim X As Long, Y As Long 
X = 1 ' colonne B 
Y = 6 ' ligne 7 

maCellule = maTabl e.getCellByPosition(X,Y) 

Une zone de cellules contigues est un objet que nous pouvons obtenir a partir de ses 
coordonnees : 

Dim zoneCellule As Object 

zoneCellule = maTabl e . getCell RangeByName("B3 : C4") 
zoneCellule. BackColor = RGB(255 , 204 , 255) ' couleur de fond 

De maniere similaire a une cellule, on peut obtenir une zone de cellules a partir des 
coordonnees XI , Yl , X2 , Y2 , designant successivement le coin haut-gauche et le coin 
bas-droit de la zone. La meme zone B2 : C4 est ainsi obtenue par : 

zoneCellule = maTabl e . getCell RangeByPosition(l, 2 , 2,3) 

Se deplacer dans un tableau 

Avec la methode getCell ByPos-iti on, il est facile de se deplacer dans un tableau. 
Dans cet exemple, nous inscrivons une valeur numerique dans des cellules en 
diagonale : 

rem Code08-05 . odt bibli : Ecri reCell ul es Modulel 
Option Explicit 

Sub Ecri reEnDi agonal e() 

Dim monDocument As Object, monTexte As Object, monCurseur As Object 
Dim maTable As Object, maCellule As Object, x As Long 
monDocument = Thi sComponent 
monTexte = monDocument. Text 
monCurseur = monTexte. createTextCursor 
monCurseur .gotoNext Paragraph (Fal se) 
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monCu rseu r . gotoNextParag raph (Fal se) 

maTabl e = monDocument . createInstance("com . sun . star . text . TextTabl e") 
maTable . i nitialize(5 , 5) ' nombre de : lignes, colonnes 
monTexte.insertTextContent(monCurseur, maTable, false) 

for x = 0 to 4 ' balayage des cellules 

maCellule = maTable. getCellByPosition(4-x, x) 
maCellule. Value = x ' remplacer le contenu de la cellule 

next 

End Sub 

Le curseur de cellule 

II existe une notion de curseur de cellule, qui sert a se deplacer de cellule en cellule. 
On le cree et on le positionne dans la meme instruction : 

Dim cursCell As Object 

cursCell = maTable. createCursorByCellName("B7") 

Le curseur de cellule permet d'effectuer quelques operations sur l'ensemble de la 
cellule : couleur de fond, format de caractere, etc. La propriete RangeName du curseur 
de cellule fournit son adresse dans le tableau, sous forme d'une chaine de caracteres, 
par exemple B7. 

II existe plusieurs methodes permettant de deplacer le curseur dans le tableau, 
comme le montre le tableau 8-29. Largument SEL de ces methodes signifie : 

• Fal se : deplacement simple ; 

• True : deplacer le curseur en selectionnant les cellules. 

La plupart des methodes renvoient True si le deplacement a pu se faire. Si la nouvelle 
position est en dehors du tableau, la methode renvoie Fal se et le curseur reste en place. 



Tableau 8-29 Deplacement du curseur de cellule de tableau 



Methode 






goRight(n,SEL) 


Boolean 


Deplacer de n cellules a droite, avec saut de ligne eventuel. 


goLeft(n,SEL) 


Boolean 


Deplacer de n cellules a gauche, avec saut de ligne eventuel. 


goUp(n,SEL) 


Boolean 


Deplacer de n cellules vers le haut. 


goDown(n , SEL) 


Boolean 


Deplacer de n cellules vers le bas. 


gotoStart(SEL) 


Aucun 


Aller a la premiere cellule, en haut a gauche. 


gotoEnd(SEL) 


Aucun 


Aller a la derniere cellule, en bas a droite. 


gotoCellByName(nom, SEL) 


Boolean 


Aller a la cellule dont I'adresse alphanumerique est donnee en 
premier argument. 
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Cet exemple colore des cellules en diagonale dans un tableau. 

rem Code08-05 . odt bibli : Ecri reCell ul es Module2 
Option Explicit 

Sub ColorierEnDiagonaleO 

Dim monDocument As Object, monTexte As Object, monCurseur As Object 

Dim maTable As Object, cursCell As Object, x As Long 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

monCurseur = monTexte. createTextCursor 

monCurseur .gotoNext Paragraph (Fal se) 

monCurseur .gotoNext Paragraph (Fal se) 

maTabl e = monDocument . createlnstance ("com . sun . star . text . TextTabl e") 
maTable . i nitial ize(5 , 5) ' nombre de : lignes, colonnes 
monTexte. insertTextContent(monCurseur, maTable, False) 

cursCell = maTabl e . createCursorByCel 1 Name("El") 

for x = 1 to 5 ' balayage des cellules 
cursCell .BackCol or = RCB(255 , 200 , 200) 
cursCell .goDown(l, False) ' descendre d'une ligne 
cursCell .goLeft(l, False) 1 reculer d'une cellule a gauche 

next 

End Sub 

Curseur etendu sur une zone de cellules 

La methode createCursorByCel 1 Name cree un curseur couvrant une seule cellule, et 
non une zone. Cependant, nous pouvons l'etendre sur plusieurs cellules d'un tableau 
en deplacant le curseur de cellule avec 1' argument True. Void un exemple : 

cursCell = maTabl e . createCursorByCel 1 Name("B3") 
cursCell .goRight(l,True) 
cursCell .goDown(l,True) 
print cursCel 1 . RangeName 

Si vous executez la sequence, elle affichera la chaine de caracteres B3:C4. La zone 
selectionnee est definie par les coordonnees des cellules en diagonale. Avec un tel 
curseur, on peut effectuer des operations communes a toutes les cellules de la zone, 
par exemple des colorations. 

Du curseur de cellule a la cellule elle-meme 

En appliquant ce que nous venons de voir, il est facile d'obtenir l'objet cellule pointe 
par un curseur de cellule : 

maCellule = maTabl e . getCel 1 ByName (cursCell .RangeName) 
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De meme pour la zone de cellules correspondant a un curseur de cellule etendu : 
zoneCellule = maTable.getCellRangeByName(cursCen .RangeName) 

Zone selectionn.ee par I'utilisateur 

Dans un tableau, I'utilisateur peut effectuer diverses selections : 

O pointer un endroit dans le texte d'une cellule ; 

0 selectionner une ou plusieurs zones dans le texte d'une cellule ; 

0 selectionner une ou plusieurs zones dans les textes de plusieurs cellules ; 

0 selectionner plusieurs cellules contigues. 

Nous disposons de deux objets pour distinguer ces cas : 

laSel = monDocument.currentSelection 

CurseurVisible = monDocument.currentcontroner.ViewCursor 

Le curseur visible est la position du curseur clignotant. II nous indique la table uti- 
lisee avec sa propriete TextTabl e et la cellule dans la table avec sa propriete Cel 1 . 

La selection courante prend des apparences differentes suivant les cas de selection 
indiques plus haut. Nous reprenons la meme numerotation. 

0 Lobjet laSel supporte le service com. sun. star. text. TextRanges (notez les 
final). Sa propriete Count vaut 1. Lobjet laSel donne acces a un seul element : 
laSel (0). 

Cet element supporte le service com. sun. star. text. TextRange. Sa propriete 
String est une chaine vide, sa propriete Cell nous donne la cellule pointee, sa 
propriete TextTabl e nous donne le tableau. 

0 Ici, la propriete Count vaut n + 1 s'il y a n zones selectionnees. Tous les elements, 
auxquels on accede par indexation, supportent le service 
com. sun. star. text. TextRange. Lun d'eux est celui indique au point 1, les autres 
donnent dans leur propriete Stri ng une des zones selectionnees. 

0 Identique au cas 2, mais la propriete Cel 1 des elements indiquent des cellules dif- 
ferentes. 

0 Lobjet laSel est totalement different; il supporte le service 
com. sun. star. text. TextTabl eCursor. Sa propriete RangeName indique les coor- 
donnees du rectangle de cellules selectionnees, exemple : "C3:B2". 

Ainsi, gerer les selections d'utilisateur dans un tableau nest pas particulierement 
simple. Et n'oubliez pas qu'il est possible de selectionner des zones dans des cellules 
de tableau et ailleurs dans le document, par exemple dans le texte principal ou dans 
un autre tableau ! 
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Les cellules 



Une cellule de tableau Writer comporte de nombreuses proprietes. Le tableau 8-30 
en liste les principales, d'autres seront decrites plus loin. 

Tableau 8-30 Proprietes de cellule de tableau 



BackColor 


Long 


Couleur du fond. 


BackTransparent 


Bool ean 


True rend le fond transparent (interface utilisateur : sans remplissage). 


TopBorder 


Object 


Structure de la hgne de bordure du haut. 


TopBorderDi stance 


Long 


Espacement par rapport a la bordure du haut. 


BottomBorder 


Object 


Structure de la ligne de bordure du bas. 


BottomBorderDi stance 


Long 


Espacement par rapport a la bordure du bas. 


LeftBorder 


Object 


Structure de la ligne de bordure gauche. 


LeftBorderDi stance 


Long 


Espacement par rapport a la bordure gauche. 


Ri ghtBorder 


Object 


Structure de la ligne de bordure droite. 


Ri ght Bo rderDi stance 


Long 


Espacement par rapport a la bordure droite. 


Cell Name 


String 


Coordonnees alphanumeriques de la cellule. 


Formula 


String 


Formule de la cellule, s'il y a lieu. 


Value 


Double 


Valeur de la cellule, si elle contient un nombre. 


String 


Stri ng 


Contenu sous forme de chame de caracteres. 


Type 


Integer 


Precise le type de contenu de la cellule. 


Text 


Object 


L'objet texte supportant le texte de la cellule. 


VertOrient 


Integer 


Position du texte par rapport au haut/bas de la cellule. 


IsProtected 


Boolean 


True si la cellule est protegee contre des modifications. 



Malgre son nom, la propriete IsProtected peut etre modifiee pour proteger ou 
deproteger une cellule. II n'y a pas de mot de passe. 



if maCel 1 ul e . IsProtectedthen 

maCellule. IsProtected = False 
end if 



Bordures de cellule 

Les proprietes de bordure de lignes (TopBorder, etc.) sont des structures deja 
decrites, voyez le tableau 8-8. 
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II faut definir une variable ayant cette structure, la remplir, puis l'affecter a la pro- 
priete de bordure : 

Dim unBord As New com. sun. star .table. Border Line 

With unBord ' pour verifier, utilisez le zoom a 200% ! 
.Color = RGB(200,0,0) 
.OuterLineWidth = 30 

maCellule.LeftBorder = unBord' ligne simple, rouge 
.OuterLineWidth = 100 

maCell ul e . RightBorder = unBord ' ligne simple, rouge 
. Inner Li neWidth = 60 
. Li neDi stance = 30 
.Color = RGB(0, 120,0) 

maCellule.TopBorder = unBord ' ligne double, verte 
.Color = RGB(0, 0,120) 

maCellule.BottomBorder = unBord ' ligne double, bleue 
End With 

Ecrire un texte dans la cellule 

Toutes les possibilites d'ecriture et de formatage de texte que nous avons decrites 
pour le texte principal sont aussi disponibles pour ecrire dans une cellule de tableau. 
II suffit d'obtenir l'objet texte associe a la cellule et de lui faire creer un curseur d'ecri- 
ture. Cet exemple ajoute un texte en rouge et en gras a la fin du premier mot de la 
cellule A2 d'une table existante. 

rem Code08-05 . odt bibli : Ecri reCell ul es Module3 
Option Explicit 

Sub InsererTexteDansCellule() 

Dim monDocument As Object, maTable As Object 

Dim maCellule As Object 

Dim monTexte As Object, monCurseur As Object 

monDocument = Thi sComponent 

maTable = monDocument. TextTabl es . getByName("Resul tats") 

maCellule = maTable. getCel 1 ByName("A2") 

monTexte = maCellule. Text 

monCurseur = monTexte. createTextCursor 

monCurseur .gotoEnd0fWord(fal se) 

monCurseur. CharWeight = com . sun . star . awt . FontWei ght . BOLD 
monCurseur. CharColor = RGB(250,0,0) 'Rouge 
monTexte. insertString(monCurseur, " 2004", false) 
End Sub 

La propriete Text de l'objet cellule renvoie l'objet cellule lui-meme. La propriete 
Stri ng de la cellule donne le texte sous forme de chaine de caracteres. 
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La propriete VertOrient permet de positionner le texte dans la cellule. Elle utilise 
des constantes nominees indiquees dans le tableau 8-31, par exemple : 

maCel 1 ul e . VertOri ent = com . sun . star . text . VertOri entati on . CENTER 



Tableau 8-31 Constantes de positionnement vertical 







NONE 


Position en haul 


CENTER 


Position au milieu. 


BOTTOM 


Position en bas. 



Formules et valeurs numeriques 

Les cellules d'un tableau Writer peuvent comporter des nombres ou des formules fai- 
sant reference au contenu de diverses cellules. Ne confondez pas avec un contenu 
texte qui representerait un nombre ou une formule. 

La propriete Value d'un objet cellule sert a affecter une valeur dans la cellule. Cette 
propriete est du type Double. Les nombres avec decimales sont ecrits en Basic avec 
un point decimal, mais le tableau les affiche en tenant compte des specificites natio- 
nales (la virgule en francais). 

On remplit une cellule avec une formule en utilisant la propriete Formula, de type 
Stri ng. Laide en ligne de Writer explique comment obtenir des formules. 

Le format d'affichage d'un nombre dans une cellule depend de sa propriete 
NumberFormat, de type Long. Cette valeur est un index dans la collection des formats 
disponibles dans le document. Ce concept est decrit au chapitre 7 a la section « Les 
formats de nombre ». 

Cet exemple calcule la somme de plusieurs cellules dans le tableau Finances. II 
montre aussi que la propriete Stri ng de la cellule renvoie alors la chaine de caracteres 
correspondant a la valeur numerique de la cellule. 

rem Code08-05 .odt bibli : Ecri reCell ul es Module4 
Option Explicit 

Sub ValeursEtFormulesO 

Dim monDocument As Object, maTable As Object 
Dim maCellule As Object 
monDocument = Thi sComponent 

maTable = monDocument .TextTabl es . getByName("Fi nances") 

maCellule = maTable. getCell ByName("B2") 

maCellule. Value = 2200.55 

maCellule = maTable. getCell ByName("B3") 
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maCellule. Value = 15260 
maCellule = maTabl e . getCell ByName("B4") 
maCellule. Value = 15.75 + 22.3 + 2.35*4 
print "Cellule B4 : " & maCel 1 ul e . Stri ng 
maCellule = maTabl e . getCel 1 ByName("B5") 
maCellule. Formula = "sum(<B2 : B4>)" 

print "Resultat de la cellule B5 : " & maCell ul e . Stri ng 
End Sub 

L'expression affectee a la cellule B4 est en realite calculee par Basic et la cellule ne 
recoit que le nombre resultant. 

La pseudo-propriete Type de l'objet cellule indique le type de donnees quelle con- 
tient. Elle est en lecture seule. Les valeurs possibles sont des constantes nominees, 
listees au tableau 8-32. Exemple : 

if maCellule. Type = com . sun . star . tabl e . Cell ContentType . FORMULA then 

' la cellule contient une formule 
end if 



Tableau 8-32 Types de contenu de cellule 



EMPTY 


La cellule est vide. 


VALUE 


La celule contient un nombre. 


TEXT 


La cellule contient un texte. 


FORMULA 


La cellule contient une formule. 



La propriete DataArray d'une zone de cellules renvoie un tableau de lignes, dont 
chaque ligne est un tableau de valeurs Variant, une par cellule de la ligne. Chaque 
Variant donne le contenu de la cellule, de type String ou Double. C'est un moyen 
pratique d'explorer rapidement les cellules d'une zone. Calculons par exemple la 
somme des valeurs d'une zone de cellules : 

Dim vTable As Variant, vLigne As Variant 
Dim x As Long, y As Long, somme As Double 

vTable = zoneCel 1 ul e . DataArray 

somme = 0 

for y = 0 to UBound(vTableO) ' chaque ligne 
vLigne = vTable(y) 

for x = 0 to UBound(vLigneO) ' chaque cellule de la ligne 

somme = somme + vLigne (x) 
next 
next 

MsgBox ("Total : " & somme) 
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Comme DataArray renvoie un tableau de tableaux, il n'est pas possible d'acceder 
directement a une cellule avec deux index. On doit done passer par une variable 
intermediate, vLigne. 

Trier un tableau 

Un objet tableau de Writer fournit une methode de tri (en anglais, Sort). Cependant, 
cette methode est peu utilisable directement, car elle trie tout le tableau alors qu'en 
general un tableau comporte des en-tetes de colonnes ou de lignes qui doivent rester 
inchanges dans le tri. En pratique, nous definirons un objet zone de cellules couvrant 
les cellules a trier dans le tableau. Cette zone de cellules fournit elle aussi la methode 
de tri Sort. 

Nous allons effectuer un tri de la troisieme colonne d'un tableau nomme Triage. 
Voici l'ensemble du code, que nous expliquerons progressivement. 

rem Code08-05 . odt bibli : Trier Modulel 
Option Explicit 

Sub TrierTableParCouleurO 

Dim MonDocument As Object 

Dim MaTable As Object, zoneDeTri As Object 

Dim ConfigTri(O) As New com. sun. star. table. Tabl eSortFi eld 

Dim DescrTri As Variant 

MonDocument = Thi sComponent 

MaTable = MonDocument. TextTabl es .getByName ("Tri age") 

With ConfigTri(O) 

.Field = 3 ' colonne C = "Couleurs" 
. IsAscending = true 

. IsCaseSensiti ve = MsgBox("Di fferenci er la Casse ?", 4) = 6 
.FieldType = com . sun . star . tabl e .Tabl eSortFi eldType .ALPHANUMERIC 
End With 

zoneDeTri = MaTabl e . getCel 1 RangeByName("A2 : D14") 
DescrTri = zoneDeTri . createSortDescriptor 
setPropVal (DescrTri , "SortFields" , ConfigTn'O) 
setPropVal (DescrTri , "IsSortCol umns" , false) 
setPropVal (DescrTri , "IsSortlnTabl e" , true) 

zoneDeTri .Sort (DescrTri ()) 

End Sub 

La methode de tri a besoin d'un descripteur de tri (notre variable DescrTri) qui pre- 
cise les conditions globales de tri. Parmi celles-ci, nous trouvons l'element 
SortFields qui contient un tableau (Array) de descripteurs, un par colonne a trier 
(notre variable ConfigTri). Nous allons maintenant decrire chaque descripteur. 
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Le descripteur de tri par colonne est une structure composee des elements detailles 
dans le tableau 8-33. 



Tableau 8-33 Descripteur de tri par colonne 



lement 



Field 


Long 


Rang de la colonne dans la zone de cellules. 
Valeur 1 pour la premiere colonne. 


IsAscendi ng 


Boolean 


True pour un tri par ordre croissant. 


IsCaseSensiti ve 


Boolean 


True pour tenir compte de la casse des caracteres. 


Fi el dType 


Integer 


Type du champ. Constante nommee, decrite ci-dessous. 


CollatorLocale 


Object 


Langue utilisee pour les fonctions dependant de la locali- 
sation. Voir la notion de Locale dans le chapitre 7. 


Col 1 atorAl gori thm 


Stri ng 


Methode de tri. 



L' element Fi el dType a trois valeurs possibles, dont deux sont evidentes : 

com . sun . star . tabl e . Tabl eSortFi el dType . ALPHANUMERIC 
com . sun . star . tabl e . Tabl eSortFi el dType . NUMERIC 
com . sun . star . tabl e . Tabl eSortFi el dType . AUTOMATIC 

Avec AUTOMATIC, OpenOffice.org decide lui-meme si le type est numerique ou 
alphanumerique, alors autant ne pas l'utiliser. 

Lelement CollatorLocale est lui-meme une structure Locale. Pour les cas courants 
(francais, anglais, espagnol, allemand...), il n'est pas necessaire de le remplir. De 
meme, Col 1 atorAl gori thm peut etre omis car il n'y a actuellement pas de choix pos- 
sible (la seule valeur possible est al phanumeri c). 

Une fois rempli le descripteur de tri par colonne, nous definissons la zone de tri dans 
le tableau, en excluant la premiere ligne qui contient les en-tetes de colonnes. 

Le descripteur global de tri est obtenu avec la methode createSortDescri ptor de 
l'objet zoneDeTri . Ce descripteur est un tableau (Array) de structures PropertyVal ue. 
Chacune de celles-ci comporte un nom et une valeur. Le tableau 8-34 liste ces pro- 
prietes. Les noms sont initialises par createSortDescri ptor, mais l'ordre des pro- 
prietes dans le tableau de structures depend de l'implementation. La routine utilitaire 
setPropVal recherche la propriete d'un nom donne et lui affecte la valeur qui est en 
argument. Cette routine, declaree dans la bibliotheque Standard du document exemple, 
est decrite a l'annexe B. 
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Tableau 8-34 Descripteur global de tri 




IsSortColumns 



Boolean 



Fal se pour trier par colonne (intervertir les lignes). 
True pour trier par lignes (intervertir les colonnes). 



SortFields 



Array(Object) 



Tableau des descripteurs de tri par colonne. 



IsSortlnTable 



Boolean 



True pour trier un tableau. 



MaxSortFieldsCount Long 



Delimiter Integer 



Non utilise pour le tri d'un tableau. 

En lecture seule, nombre maximal de colonnes a trier, 
valeur actuelle = 3. 



L' element IsSortCol umns, au nom particulierement mal choisi, indique si on trie par 
colonne (notre cas, le cas courant), ou si on trie des lignes (dans ce cas, le tableau aura 
des en-tetes de lignes et tout se passe comme si on avait tourne le tableau de 
90 degres). Nous continuons sur notre exemple de tri de colonnes, sachant qu'il suffit 
de remplacer le terme ligne par colonne dans le deuxieme cas. 

L'element IsSortlnTable vaut ici toujours True. La valeur False et l'element 
Delimiter sont utilises pour des tris de paragraphes de texte, que nous ne developpe- 
rons pas (nous n'avons pu le faire fonctionner). 

L'element MaxSortFieldsCount est pour nous une constante. Dans la version actuelle 
d'OpenOffice.org, on peut trier sur un maximum de 3 colonnes, comme on le verra 
dans l'exemple suivant. 

Une fois le descripteur global de tri initialise, la table est triee avec la methode Sort. Si 
vous executez la macro sur le document fourni dans le Zip telechargeable, vous pourrez 
voir comment s'effectue le tri avec ou sans prise en compte de la casse. Pour revenir a 
l'ordre initial de la table, utilisez le bouton Annuler sur la fenetre Writer, ou executez la 
macro TrierTableParLignes qui est dans le module 3 de la meme bibliotheque. 

Le tableau Tri age est suffisamment rempli pour permettre de trier sur trois colonnes 
successivement. Nous utilisons maintenant un tableau de 3 descripteurs de colonnes, 
qui sont prises en compte dans le meme ordre que ces descripteurs. Les deux pre- 
mieres colonnes contiennent des textes, la troisieme des nombres. 

rem Code08-05 . odt bibli : Trier Module2 
Option Explicit 

Sub TrierTableSur3Colonnes() 

Dim MonDocument As Object 

Dim MaTable As Object, zoneDeTri As Object 

Dim ConfigTri(2) As New com. sun. star. table. TableSortField 

Dim DescrTri As Variant 
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MonDocument = Thi sComponent 

MaTable = MonDocument. TextTabl es . getByName("Tri age") 

ConfigTri (0) . Field = 3 ' colonne C = "Couleur" 
Conf i gTri (0) . IsAscendi ng = true 
Conf i gTri (0) . Fi el dType = _ 

com . sun . star . tabl e .Tabl eSortFi el dType .ALPHANUMERIC 
Conf i gTri (1). Field = 2 ' colonne B = "Ville" 
Conf i gTri (1) . IsAscendi ng = true 
Conf i gTri (1) . Fi el dType = _ 

com . sun . star . tabl e .Tabl eSortFi el dType .ALPHANUMERIC 
Conf i gTri (2) . Fi el d = 4 ' colonne D = "Nombre" 
Conf i gTri (2) . IsAscendi ng = false 
Conf i gTri (2) . Fi el dType = _ 

com . sun . star . tabl e .Tabl eSortFi el dType . NUMERIC 

zoneDeTri = MaTabl e . getCel 1 RangeByName("A2 : D14") 
DescrTri = zoneDeTri . createSortDescri ptor 
setPropVal (DescrTri , "SortFi el ds" , ConfigTri ()) 
setPropVal (DescrTri , "IsSortCol umns" , false) 
setPropVal (DescrTri , "IsSortlnTabl e" , true) 

zoneDeTri . Sort(DescrTri ()) 
End Sub 

Executez la macro et etudiez attentivement le resultat : il existe des lignes qui neces- 
sitent les trois criteres pour les classer. 



BOGUE Prise en compte de la casse 

D'apres nos essais, la prise en compte de la casse ne fonctionne pas sur un tri a plusieurs colonnes. 



Le tri de tableau est decrit dans le SDK a l'interface XSortable et aux services 
SortDescri ptor2 et Tabl eSortDescri ptor2. 

Tableaux irreguliers 

Jusqu'a maintenant, nous avons traite des tableaux constitues d'un quadrillage regu- 
lier. Pour des questions d'esthetique ou de titrage, il est parfois necessaire de 
fusionner plusieurs cellules contigues, ou de scinder une cellule. 

Scinder et fusionner des cellules 

Pour fusionner une zone de cellules, on doit d'abord etendre un curseur de cellule sur 
la zone concernee, puis utiliser sa methode mergeRange. 



Manipuler les documents OpenOffice.org 

Troisieme partie 



cursCell = maTabl e . createCursorByCel 1 Name("B3") 
cursCell .goRight(l, true) 
cursCell .goDown(l, true) 

cursCell . mergeRange' fusionner la zone B3:C4 

Si les cellules selectionnees contenaient du texte, les paragraphes seront accoles dans 
la cellule resultante. 

Toujours avec un curseur de cellule, on scinde horizontalement ou verticalement une 
cellule en plusieurs sous-cellules avec la methode mergeRange : 

cursCell = maTabl e . createCursorByCel 1 Name("C4") 
cursCell . spl it Range (2 .True) ' scinder horizontalement 

Le premier argument de splitRange est le nombre de cellules resultantes ; le 
deuxieme argument vaut False pour scinder verticalement, et True pour scinder 
horizontalement. 

Les coordonnees dans un tableau irregulier 

Scinder ou fusionner des cellules dans un tableau entraine une modification des 
coordonnees de cellules. La version 3.0 d'OpenOffice.org a totalement change la 
notation des coordonnees, par rapport aux versions precedentes. Par exemple, a la 
suite de fusion/scission des coordonnees de cellules comme A3. 1.2 apparaissaient. 
Maintenant, les coordonnees restent simples. 

ASTUCE Voir les coordonnees d'une cellule 

Dans un tableau Writer, le fait de cliquer dans une cellule affiche ses coordonnees en bas de la fenetre 
Writer, dans la barre d'etat. 

Partons d'un tableau regulier de 4 colonnes sur 5 lignes. La figure 8-2 indique les 
coordonnees de chaque cellule. 



Figure 8-2 

Cellules d'un tableau regulier 



A1 


B1 


C1 


D1 


A2 


B2 


C2 


D2 


A3 


B3 


C3 


D3 


A4 


B4 


C4 


D4 


A 5 


B5 


C5 


D5 



Fusionnons la zone B3:C4. La figure 8-3 indique les nouvelles coordonnees resul- 
tantes. Le triangle noir pointe les cellules qui ont change de coordonnees : les cellules 
a droite de la fusion ont ete renumerotees. 
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Figure 8-3 

Coordonnees des cellules 
apres fusion 



A1 


B1 


C1 


D1 


A2 


B2 


C2 


D2 


A3 


► B3 


► C3 


A4 


► CA 


A5 


B5 


C5 


D5 



Scindons verticalement la cellule A2 en 3 cellules. Dans la figure 8-4 le triangle noir 
pointe toujours les cellules modifiees par rapport au tableau regulier initial. Sur la 
deuxieme ligne, les cellules a droite de la cellule scindee ont ete renumerotees. 



Figure 8-4 

Coordonnees des cellules 
apres scission verticale 



A1 


B1 


C1 


D1 


► ► ► 

A2 B2 C2 


► D2 


► E2 


► F2 


A3 


► B3 


► C3 


A4 


► CA 


A5 


B5 


C5 


05 



A present, scindons horizontalement la cellule E2 en 3 cellules. La figure 8-5 montre 
le resultat. Le double triangle indique les cellules qui ont ete de nouveau numerotees. 



Figure 8-5 

Coordonnees des cellules 
apres scission horizontale 



A1 


B1 


C1 


D1 


A2 


B2 


► 

C2 


► D2 


► E2 


► F2 


► E3 


► E4 


► A5 


► ► B5 


► ► C5 


► A6 


► ► C6 


► A 7 


► B7 


► C7 


► D7 



Si on explore ce tableau manuellement, en mettant le curseur sur la cellule Al et en 
utilisant plusieurs fois la touche Tabulation, on obtient successivement : 

Al Bl CI Dl 

A2 B2 C2 D2 E2 F2 

A2 B2 C2 D2 E3 F2 

A2 B2 C2 D2 E4 F2 

A5 B5 C5 

A6 B5 C6 

A7 B7 C7 D7 
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Ainsi, la meme cellule (par exemple la cellule B2) est vue plusieurs fois. On ne peut 
done pas explorer facilement un tableau irregulier. La pseudo-propriete Cel 1 Names 
d'un tableau Writer renvoie une donnee tableau contenant les noms de chaque cellule 
du tableau Writer, mais classes dans l'ordre des numeros de lignes puis de gauche a 
droite dans chaque ligne, avec une seule apparition de chaque cellule. 

Que donnent Rows. Count et Columns. Count pour un tableau irregulier ? Les essais 
semblent montrer que le nombre de colonnes est celui de la premiere ligne, alors que 
le nombre de lignes est le nombre maximal de cellules verticalement. 

II n'est pas toujours possible de deplacer un separateur de colonne dans une ligne de 
tableau irregulier. Cela depend de la situation du separateur par rapport a la structure 
du tableau. 



Les cadres 

Les cadres de texte ont bien des usages dans un document Writer, par exemple pour 
placer librement une zone pouvant contenir du texte, une image, etc. En anglais, le 
mot cadre se traduit par frame. 

Jargon Frame 

La documentation API emploie souvent le mot frame pour designer aussi une fenetre elementaire. 

Inserer un cadre 

On utilise un curseur pour designer l'endroit d'insertion du cadre. La methode 
createlnstance de l'objet document fournit un nouvel objet cadre. II est ainsi reper- 
torie dans l'ensemble des cadres du document. Linsertion effective du cadre sera 
faite par la methode i nsertTextContent de l'objet texte. 

Largument de createlnstance doit etre ecrit en respectant la casse. 

Le troisieme argument de la methode i nsertTextContent signifie : 

• Fal se = inserer dans le texte ; 

• True = ecraser la zone actuellement selectionnee par le curseur. 
Lexemple utilisait le minimum d'instructions. En pratique, il faut preciser : 

• si la hauteur du cadre s'adapte a son contenu ou non ; 

• par rapport a quoi le cadre se positionne (l'ancrage du cadre) ; 

• sa position, absolue par rapport a l'ancre ou relative. 
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rem Code08-06 . odt bibli : AjoutCadre Modulel 
Option Explicit 

Sub InsererUnCadreO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object, monCadre As Object 
monDocument = Thi sComponent 
monTexte = monDocument .Text 
monCurseur = monTexte. createTextCursor 
monCu rseu r . gotoNextParag raph (Fal se) 
monCurseur . gotoNextParag raph (Fal se) 
1 monCurseur est dans le troisieme paragraphe 

monCadre = monDocument . createInstance("com . sun . star . text . TextFrame") 

monCadre .Width = 10400' 104 mm largeur 

monCadre. Height = 2530' 25,3 mm de haut 

monTexte. insertTextContent(monCurseur, monCadre, false) 

End Sub 

Ces notions seront precisees un peu plus loin. 



Inserer plusieurs cadres 

A chaque insertion d'un cadre, il est necessaire d'obtenir un nouvel objet TextFrame, 
meme si on insere plusieurs fois le meme cadre. II faut aussi reinitialiser a chaque fois 
les proprietes du cadre. Dans cet exemple, on insere deux cadres dans deux paragra- 
phes du document Writer : 

rem Code08-06 . odt bibli : AjoutCadre Module2 
Option Explicit 

Sub InsererPlusieursCadresO 

Dim monDocument As Object, monTexte As Object 

Dim monCurseur As Object, monCadre As Object 

monDocument = Thi sComponent 

monTexte = monDocument .Text 

monCurseur = monTexte. createTextCursor 

monCu rseu r . gotoNextParag raph (Fal se) 

monCu rseu r . gotoNextParag raph (Fal se) 

' monCurseur est dans le troisieme paragraphe 

monCadre = monDocument . createInstance("com . sun . star . text .TextFrame") 

monCadre. Width = 10400 ' 104 mm largeur 

monCadre. Height = 2530 ' 25,3 mm de haut 

monTexte. insertTextContent(monCurseur, monCadre, false) 

monCu rseu r . gotoNextParag raph (Fal se) 

1 monCurseur est dans le quatrieme paragraphe 

monCadre = monDocument . createInstance("com . sun . star . text .TextFrame") 
monCadre. Width = 1500 ' 15 mm largeur 
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monCadre. Height = 3000 ' 30 mm de haut 

monTexte. insertTextContentCmonCurseur , monCadre, false) 

End Sub 

Trouver un cadre 

Rappelons que tout cadre possede un nom (par defaut, en version francaise : Cadrel, 
Cadre2, etc. par ordre de creation). Avec le Navigateur, on peut donner un nom plus 
specifique a chaque cadre. 

Supposons que dans un document existant, nous ayons a modifier le contenu d'un 
cadre nomme Encadre. L'objet document fournit la collection de ses cadres avec la 
fonction getTextFrames (notez le s du pluriel) et on obtient un tableau d'un nom 
particulier avec la fonction getByName de l'objet collection. On peut aussi acceder a 
un cadre par son numero d'ordre avec la methode getBylndex. Avec OOoBasic, le 
getBylndex peut etre omis, comme si on indexait une variable tableau. 

monCadre = monDocument .TextFrames . getByName("Encadre") 

Nous pouvons maintenant modifier le cadre en utilisant la variable monCadre. 

Le getByName declenchera une exception s'il n'existe aucun cadre de ce nom. Vous 
pouvez verifier qu'un tel nom de cadre existe : 

"if monDocument. TextFrames. hasByName("Encadre") then 

' le cadre existe, le modifier 
end if 

II est facile de renommer un cadre avec sa propriete Name. Notons qu'un nom de 
cadre ne doit pas comporter de caractere espace. 

monCadre = monDocument. TextTabl es . getByName("Encadre") 
monCadre. Name = "Cadre_allonge" 

L'objet TextFrames nous permet de connaitre tous les cadres du document et done de 
les modifier. Le nombre de cadres est fourni par la propriete Count, leurs noms sont 
obtenus avec la propriete Name de chaque objet cadre. 

rem Code08-06 . odt bibli : AjoutCadre Module3 
Option Explicit 

Sub ListerLesCadresO 
Dim monDocument As Object 

Dim lesCadres As Object, monCadre As Object 
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Dim x As Long 

monDocument = Thi sComponent 
lesCadres = monDocument. TextFrames 
for x = 0 to lesCadres. Count -1 

monCadre = lesCadres (x) 

print "Cadre : " & monCadre. Name 
next 
End Sub 

Attention, l'ordre des cadres dans la liste de TextFrames ne correspond pas necessai- 
rement a l'ordre dans le document. 

Supprimer un cadre 

On utilise la methode removeTextContent de l'objet texte. 
monTexte . removeTextContent (monCad re) 



Dimensionner un cadre 

La largeur et la hauteur d'un cadre sont reglees respectivement par ses proprietes 
Width et Height, exprimees en 1/100 de millimetres. 

La largeur et la hauteur du cadre peuvent s'adapter ou non au contenu du cadre, par 
exemple si on y inscrit du texte sur plusieurs lignes. Ceci est defini respectivement 
par les proprietes WidthType et SizeType, de type Integer, qui recoivent une cons- 
tants nommee (voir le tableau 8-35), par exemple : 

monCadre. SizeType = com . sun . star . text . Si zeType . FIX 



Tableau 8-35 Constantes dimensionnelles de cadre 



Constante 


Signification en largeur 


Signification en hauteur 


VARIABLE 


La largeur depend du contenu. 


La hauteur depend du contenu. 


FIX 


La largeur est fixe, indiquee par Wi dth. Valeur par 
defaut. 


La hauteur est fixe, indiquee par Hei ght. 


MIN 


Wi dth indique la largeur minimale 


Hei ght indique la hauteur minimale (valeur 
par defaut). 
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Positionner le cadre 

Un cadre est positionne : 

1 soit de maniere absolue, en precisant la distance en 1/100 de millimetre entre le 
coin haut-gauche de l'ancre et le coin haut-gauche du cadre, 

2 soit de maniere relative, c'est-a-dire en decrivant sa situation par rapport a une 
zone qui englobe le cadre. Cette zone englobante doit aussi etre precisee. 

Le positionnement absolu ou relatif peut etre choisi independamment pour la posi- 
tion horizontale et pour la position verticale. 

Les nombreuses combinaisons possibles d'ancrage / zone englobante / position rela- 
tive donnent des resultats parfois identiques, ou visibles seulement avec des tailles de 
cadre et de paragraphe compatibles. Faites des essais. 

Si vous inserez manuellement un cadre dans un texte, un clic droit sur le cadre donne 
acces aux proprietes d'ancrage et d'alignement. Lalignement correspond au position- 
nement relatif du cadre. 

Les differents ancrages de cadre 

Le choix du type d'ancrage se fait en affectant a la propriete Anchor-Type de type 
Integer, une constante nommee (tableau 8-36), par exemple : 

| monCadre . AnchorType = com. sun . star . text .TextContentAnchorType .AT_PAGE 
Tableau 8-36 Constantes d'ancrage de cadre 





Signification 


AT_ PARAGRAPH 


Ancrage par rapport au paragraphe pointe par le curseur (valeur par 
defaut). 


AS_CHARACTER 


Ancrage comme si le cadre etait un caractere ; la hauteur de la ligne 
s'adapte a la taille du cadre. 


AT_PAGE 


Ancrage par rapport a la page. 

AnchorPageNo contient le numero de page ; par defaut, c'est la 
page ou se trouve le curseur d'ecriture. 


AT_FRAME 


Ancrage dans un cadre. 

AnchorFrame contient le cadre qui servira d'ancrage. 


AT_CHARACTER 


Ancrage par rapport au caractere pointe par le curseur. 



Positionnement horizontal 

Le positionnement depend des proprietes de cadre HoriOrient, 
HoriOrientRelation et AnchorType que nous avons dejavue. 
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La propriete HoriOrient, de type Integer, utilise des constantes nominees 
(tableau 8-37), exemple : 



I 



monCadre . Hon' On' ent = com . sun . star . text . Hon' On' entati on . NONE 

Tableau 8-37 Constantes de HoriOrient 
Signification 



NONE 


Positionnement absolu. 

La position en 1/100 de mm est alors donnee par la propriete 
Horn Orient Position 


RIGHT 


Positionnement relatif, a droite dans la zone englobante. 


LEFT 


Positionnement relatif, a gauche dans la zone englobante. 


CENTER 


Positionnement relatif, au centre dans la zone englobante. 



La propriete HoriOrientRelation, de type Integer, precise la zone englobante. Elle 
utilise des constantes nominees, exemple : 



monCadre. HoriOrientRelation = 

com . sun . star . text . RelOri entati on . PAGE_LEFT 



Le tableau 8-38 indique les valeurs admises. La colonne repere est utilisee pour les 
explications qui suivent. 



Tableau 8-38 Constantes de HoriOrientRelation 



FRAME 


a 


Le paragraphe entier, y compris ses marges. 


PRINT_AREA 


b 


Le paragraphe entier, sans ses marges. 


CHAR 


c 


Le caractere. 


PAGE_LEFT 


d 


La marge de gauche de la page ; en principe le cadre doit etre assez 
petit pour tenir a I'interieur de la marge 


PAGE_RIGHT 


e 


La marge de droite de la page ; meme remarque. 


FRAME_LEFT 


f 


La marge de gauche du paragraphe ; meme remarque. 


FRAME_RIGHT 


9 


La marge de droite du paragraphe ; meme remarque. 


PAG E_ FRAME h 


La page entiere, y compris ses marges. 


PAGE_PRINT_AREA i 


La page entiere sans ses marges. 
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Le positionnement absolu est le plus simple : il suffit de preciser la distance en 1/100 
de millimetre entre le coin haut-gauche de l'ancre et le coin haut-gauche du cadre. 

monCadre . HoriOrient = com. sun . star . text . HoriOri entation . NONE 
monCadre . HoriOrientPosition = 2500 ' 25 mm 

Pour un positionnement relatif, HoriOrientRelation n'utilise que certaines valeurs, 
selon l'ancrage : 

• pour un ancrage AT_PARACRAPH, les valeurs reperees par a, b (par defaut), d, e, f, g 

• pour un ancrage AT_ FRAME, les valeurs reperees par a, b (par defaut), d, e, f, g 
dans ce contexte, il s'agit du paragraphe de texte a l'interieur du cadre englobant 

• pour un ancrage AT_PACE, les valeurs reperees par d, e, h, i (par defaut). 
Exemple de positionnement relatif : 

monCadre. AnchorType = 

com . sun . star . text . TextContentAnchorType . AT_PARAGRAPH 
monCadre . Horn Ori ent = com . sun . star . text . HoriOri entati on . RIGHT 
monCadre. HoriOrientRelation = 
com . sun . star . text . RelOri entati on . PAGE_LEFT 



Positionnement vertical 

Le positionnement depend des proprietes de cadre VertOrient, 
VertOrientRelation et AnchorType que nous avons dejavue. 

La propriete VertOrient, de type Integer, utilise des constantes nominees 
(tableau 8-39), par exemple : 



I 



monCadre. VertOrient = com. sun. star. text. VertOrientation. NONE 



Tableau 8-39 Constantes de VertOrient 




NONE 


Positionnement absolu. 

La position en 1/100 de mm est alors donnee par la propriete VertOri entPosi ti on 


TOP 


Positionnement relatif, en haut dans la zone englobante. 


BOTTOM 


Positionnement relatif, en bas dans la zone englobante. 


CENTER 


Positionnement relatif, au centre dans la zone englobante. 
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La propriete VertOrientRelation, de type Integer, precise la zone englobante. Elle 
utilise elle aussi des constantes nominees, par exemple : 



I 



monCadre . VertOri entRel ati on = com . sun . star . text . Rel Ori entati on . FRAME 



Le tableau 8-40 indique les valeurs admises. La colonne repere est utilisee pour les 
explications qui suivent. 



Tableau 8-40 Constantes de VertOrientRelation 







FRAME 


a 


Le paragraphe entier, y compris ses marges. 


PRINT_AREA 


b 


Le paragraphe entier, sans ses marges. 


CHAR 


c 


Le caractere. 


PAGE_LEFT 


d 


La marge de gauche de la page ; en principe le cadre doit etre assez 
petit pour tenir a I'interieur de la marge 


PAGE_RIGHT 


e 


La marge de droite de la page ; meme remarque. 


FRAME_LEFT 


f 


La marge de gauche du paragraphe ; meme remarque. 


FRAME_RIGHT 


9 


La marge de droite du paragraphe ; meme remarque. 


PAGE_FRAME 


h 


La page entiere, y compris ses marges. 


PAGE_PRINT_AREA i 


La page entiere sans ses marges. 



Le positionnement absolu est le plus simple : il suffit de preciser la distance en 1/100 
de millimetre entre le coin haut-gauche de l'ancre et le coin haut-gauche du cadre. 

monCadre. VertOrient = com. sun. star. text. Hori Ori entati on. NONE 
monCadre. VertOrientPosition = 5500 ' 55 mm 

Pour un positionnement relatif, VertOrientRelation n'utilise que certaines valeurs, 
selon l'ancrage : 

• pour un ancrage AT_PARAGRAPH, les valeurs reperees par a, b (par defaut), d, e, f, g 

• pour un ancrage AT_ FRAME, les valeurs reperees par a, b (par defaut), d, e, f, g 
dans ce contexte, il s'agit du paragraphe de texte a I'interieur du cadre englobant 

• pour un ancrage AT_PAGE, les valeurs reperees par d, e, h, i (par defaut). 
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Exemple de positionnement relatif : 
monCadre . AnchorType = 

com. sun . star . text .TextContentAnchorType . AT_PARAGRAPH 
monCadre.VertOrient = com. sun. star. text. VertOrientation. TOP 
monCadre. VertOrientRelation = 
com. sun . star . text . RelOri entati on . PAGE_LEFT 

Maintenant, voici un exemple complet dans lequel on cree un petit cadre, situe au 
centre de la marge gauche de la page et verticalement en haut d'un paragraphe de 
plusieurs lignes qui sert d'ancrage. 

rem Code08-06 . odt bibli : Posi ti onCadre Modulel 
Option Explicit 

Sub PositionnerCadreO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object, monCadre As Object 
Dim x As Long 

monDocument = Thi sComponent 

monCadre = monDocument . createlnstance( "com . sun . star .text .Text Frame") 
With monCadre 

.Width = 1000 ' 10 mm largeur 

.Height = 800 1 8 mm de haut 

.SizeType = com . sun . star . text . Si zeType . FIX 

.AnchorType = com . sun . star . text . TextContentAncho rType . AT_PARAGRAPH 
.VertOrient = com. sun . star . text .VertOri entation .TOP 
. VertOrientRelation = com . sun . star . text . RelOri entation . FRAME 
.HoriOrient = com. sun . star . text . HoriOri entation . CENTER 
. HoriOrientRelation = com . sun . star . text . RelOri entation . PAGE_LEFT 
End With 

monTexte = monDocument. Text 

monCurseur = monTexte. createTextCursor 

for x = 1 to 5 ' aller au si xi erne paragraphe 

monCurseur . gotoNext Pa rag raph(Fal se) 
next 

monTexte. insertTextContent(monCurseur, monCadre, false) 
monCadre. Text. St ring = "X" 
End Sub 

Pour apprecier les positionnements, essayez pour VertOrient les valeurs CENTER et 
BOTTOM, et pour HoriOrient les valeurs LEFT et RIGHT. Remarquez aussi que pour 
VertOrientRelation, les trois valeurs FRAME donnent le meme resultat. 
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Adaptation du texte 

La propriete Surround, de type Integer, correspond a Adaptation du texte quand on 
fait un clic droit sur un cadre selectionne. Cette propriete recoit une constante 
nommee (tableau 8-41), par exemple : 

monCadre . Surround = com . sun . star . text .WrapTextMode . NONE 
Tableau 8-41 Constantes de la propriete de cadre Surround 



NONE 


Pas d'adaptation. Valeur par defaut. 


THROUGHT 


Continu (le texte continue sous le cadre). 


PARALLEL 


Renvoi dynamique a la page (texte reparti a gauhe et a droite du cadre) 


DYNAMIC 


Decide par Writer selon la situation. 


LEFT 


Le texte est a gauche du cadre 


RIGHT 


Le texte est a droite du cadre. 



La propriete SurroundAnchorOnly, de type Boolean, correspond a l'adaptation 
« Premier paragraphe ». 



Texte en colonnes 

Le texte d'un cadre peut etre reparti en colonnes. II s'agit toujours d'un seul texte, qui 
« coule » d'une colonne a la suivante. La description des colonnes est obtenue avec la 
propriete TextColumns du cadre. On retiendra de cet objetles proprietes indiquees au 
tableau 8-42. II faut fixer le nombre de colonnes avec la propriete Col umnCount avant 
de fixer les autres proprietes. 

Tableau 8-42 Proprietes de TextColumns 



Col umnCount 


Integer 


Nombre de colonnes. 


Columns 


Object 


Tableau des descripteurs de colonnes. 


IsAutomati c 


Boolean 


True pour des colonnes d'egale largeur. 


Automati cDi stance 


Long 


Distance separant deux colonnes adjacentes, en 1 /1 00 de mm. 


SeparatorLi nelsOn 


Bool ean 


True pour mettre un trait vertical separateur de colonnes. 


SeparatorLi neColor 


Long 


Couleur du trait separateur de colonnes. 


SeparatorLi neRelati ve 
Height 


Long 


Hauteur du trait separateur, en pourcentage de la hauteur de colonnes. 
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Tableau 8-42 Proprietes de TextColumns (suite) 



Propriete Type Signification 


SeparatorLi neVerti cal 
Al i gnment 


Integer 


Position verticale du trait separateur. Constante nommee, voir le 
tableau 8-43. 


SeparatorLi neWi dth 


Long 


Epaisseur du trait vertical, en 1 /1 00 de mm. 



La propriete SeparatorLineVerticalAlignment recoit une constante nommee de la 
forme : 



com. sun . star . styl e . Verti cal Al "i gnment .TOP 

Tableau 8-43 Constantes de SeparatorLineVerticalAlignment 



Constante Signification 


TOP 


Trait positionne en haut du cadre. 


MIDDLE 


Trait positionne au milieu du cadre. 


BOTTOM 


Trait positionne en bas du cadre. 



La propriete Col umns de l'objet TextCol umns nous donne un tableau dont chaque ele- 
ment est une structure decrivant la colonne, comme l'illustre le tableau 8-44. Ce 
tableau est indexe a partir de zero. 



Tableau 8-44 Structure de colonne 
ropriete Type Signification 



LeftMargi n 


Long 


Marge gauche, en 1/100 de mm. 


RightMargi n 


Long 


Marge droite, en 1/100 de mm. 


Width 


Long 


Largeur de la colonne, relativement a la somme des largeurs 
des colonnes. Utilise pour des largeurs de colonnes inegales. 



Autres proprietes de cadre 

Le tableau 8-45 indique les principales autres proprietes. 

Tableau 8-45 Proprietes diverses de cadre 



Propriete Type Signification 


BackColor 


Long 


Couleur du fond. 


BackTransparent 


Bool ean 


True rend le fond transparent (interface utilisateur : sans remplissage). 


BackCol orTransparency 


Integer 


Pourcentage de transparence, valeur entre 0 et 100. 
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Tableau 8-45 Proprietes diverses de cadre (suite) 



Opaque 


Boolean 


True rend le fond opaque. 

Fal se place le cadre en arriere-plan. 


Content Protected 


Bool ean 


True pour interdire la modification du contenu. 


EditlnReadonly 


Bool ean 


True pour autoriser la modification du contenu dans un document en 
lecture seule. 


Post tionProtected 


Boolean 


True pour interdire la modification de la position. 


SizeProtected 


Boolean 


True pour interdire la modification de la taille. 


EditlnReadonly 


Boolean 


True pour autoriser I'edition du contenu si le document est en mode 
Lecture seule. 


Print 


Boolean 


True pour autoriser I'impression du cadre (valeur par defaut). 


Chai nPrevName 


Stri ng 


Norn du cadre precedent (cadres lies). 


Chai nNextName 


Stri ng 


Norn du cadre suivant (cadres lies). 


TopMargi n 


Long 


Espacement du texte par rapport au cadre, en haut. 


BottomMargi n 


Long 


Espacement du texte par rapport au cadre, en bas. 


LeftMargi n 


Long 


Espacement du texte par rapport au cadre, a gauche. 


Ri ghtMargi n 


Long 


Espacement du texte par rapport au cadre, a droite. 


BorderDi stance 


Long 


Espacement par rapport aux bordures. Permet d'imposer la meme dis- 
tance aux bordures haut, bas, gauche, droite. 


TopBorder 


Object 


Structure de la ligne de bordure du haut. Voir le tableau 8-8. 


TopBorderDi stance 


Long 


Espacement par rapport a la bordure du haut. 


BottomBorder 


Object 


Structure de la ligne de bordure du bas. Voir le tableau 8-8. 


BottomBorderDi stance 


Long 


Espacement par rapport a la bordure du bas. 


LeftBorder 


Object 


Structure de la ligne de bordure gauche. Voir le tableau 8-8. 


LeftBorderDi stance 


Long 


Espacement par rapport a la bordure gauche. 


Ri ghtBorder 


Object 


Structure de la ligne de bordure droite. Voir le tableau 8-8. 


Ri ghtBorderDi stance 


Long 


Espacement par rapport a la bordure droite. 


Shadow/Format 


Object 


Ombre du tableau. Voir le tableau 8-9 et ses explications. 


FrameStyl eName 


Stri ng 


Norn du style de cadre. 



L'exemple qui suit insere un cadre semi-transparent de couleur cyan clair, ce qui 
permet de voir le texte principal au travers. 



rem Code08-06 . odt bibli : PositionCadre Module2 
Option Explicit 
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Sub EntourageDuCadreO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object, monCadre As Object 
monDocument = Thi sComponent 

monCadre = monDocument . createInstance("com . sun . star . text . Text Frame") 
With monCadre 

.Width = 5500 1 55 mm largeur 

.Height = 2000 ' 20 mm de haut 

.BackColor = RGB (100, 2 50, 2 50) 

. BackColorTransparency = 40 ' transparent a 40% 
.Surround = com. sun. star. text. WrapTextMode.THROUGHT 
End With 

monTexte = monDocument. Text 

monCurseur = monTexte. createTextCursor 

monCurseur .gotoNextParagraph(Fal se) 

monCurseur .gotoNextParagraph(Fal se) 

1 monCurseur est dans le troisieme paragraphe 

monTexte. insertTextContent(monCurseur, monCadre, false) 

monCadre . Stri ng = "Texte par dessus" 

End Sub 



Ecrire du texte dans un cadre 

Toutes les possibilites d'ecriture et de formatage de texte que nous avons decrites 
pour le texte principal sont aussi disponibles pour ecrire dans un cadre. II suffit 
d'obtenir l'objet texte associe au cadre et de lui faire creer un curseur d'ecriture : 

Dim monTexte As Object, monCurseur As Object 

rem - - initialisation et insertion du cadre - - 

monTexte = monCadre. Text 

monCurseur = monTexte. createTextCursor 

monTexte. insertString(monCurseur, "Blabla", false) 

La propriete Text de l'objet cadre renvoie en fait l'objet cadre lui-meme. La pro- 
priete Stri ng du cadre donne le texte sous forme de chaine de caracteres. 



Les sections 

Une section de texte est un ensemble de paragraphes contigus du texte qu'on peut 
traiter globalement, par exemple le proteger contre les modifications ou le rendre 
invisible. Une section peut contenir d'autres sections, et ainsi de suite. 
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Creer une section, ecrire dedans 

Le texte d'une section n'est pas separe du texte principal, ainsi que va le demontrer 
cette macro. Executez-la ligne par ligne, en regardant attentivement le resultat dans 
le document. 

rem Code08-14 . odt bibli : Sectionsl Modulel 
Option Explicit 

Sub CreerlSectionO 

Dim monDocument As Object, monTexte As Object 

Dim curseurT As Object, curseurS As Object 

Dim maSection As Object, prgr As Integer 

prgr = com . sun . star . text . Control Character . PARAGRAPH_BREAK 

monDocument = Thi sComponent 

monTexte = monDocument .Text 

curseurT = monTexte . createTextCursor ' curseur du texte courant 

curseurT.gotoEnd(fal se) 

curseurT. gotoPreviousParagraph(Fal se) 

monTexte. i nsertStri ng(curseurT, "AAAA" , false) 

maSection = monDocument . createInstance("com . sun . star . text .TextSect ion") 
monTexte. insertTextContent(curseurT, maSection, false) 

curseurS = monTexte . createTextCursorByRange(maSection .Anchor) 

monTexte. i nsertStri ng(curseurT, "BBBB", false) 

monTexte. i nsertStri ng(curseurS, "CCCC" , false) 

curseurT. gotoNextParagraph(Fal se) ' sauter dans la section ! 

monTexte. i nsertStri ng(curseurT, "DDDD" , false) 

curseurT. gotoNextParagraph(Fal se) 1 sauter apres la section ! 

monTexte. i nsertStri ng(curseurT, "EEEE", false) 

monTexte. insertControlCharacter(curseurS, prgr, false) 

monTexte. i nsertStri ng(curseurS, "FFFF", false) 

curseurS. gotoNextParagraph(Fal se) 1 sauter apres la section ! 

monTexte. i nsertStri ng(curseurS, "CGCC", false) 

End Sub 

Commencons par ecrire AAAA dans l'avant-dernier paragraphe du texte principal. 
Pour creer une section, il nous faut un objet TextSection obtenu par la methode 
createlnstance de l'objet document. Cette nouvelle section est inseree a l'endroit 
indique par le curseur principal, curseurT. Vous constaterez quelle s'insere apres le 
paragraphe en cours. Le curseurT n'est pas affecte par cette insertion, puisque la 
sequence BBBB s'insere apres AAAA. 

Une section possede une propriete Anchor, qui est une zone de texte (TextRange). 
Nous creons un nouveau curseur, curseurS, positionne sur cette zone, qui est actuel- 
lement reduite a un point car elle ne contient pas de texte. En utilisant curseurS, 
nous inserons le texte CCCC dans la section. 
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Reprenons curseurT pour le deplacer au paragraphe suivant. L'insertion du texte 
DDDD avec le curseurT apparait au debut de la section creee ! Deplacons encore 
curseurT au paragraphe suivant. L'insertion du texte EEEE se place apres la section ! 
Ceci demontre que, du point de vue d'un curseur, les sections n' existent pas, seuls les 
paragraphes existent. 

Avec le curseurS, nous inserons un nouveau paragraphe : celui-ci est bien insere 
dans la section, comme le montre l'ecriture de FFFF. Cependant, si nous deplacons le 
curseurS au paragraphe suivant, il se retrouve hors de la section, au debut du para- 
graphe de texte principal, comme le montre l'insertion de CCGC. 

Cet exemple un peu deroutant vous montre les difficultes a travailler sur des sections. 

Naviguer dans les sections 

Comment arriver a ecrire sans se tromper sur un texte comportant des sections ? 

D'une part, il faut savoir retrouver les sections dans un document existant. Un bon 
moyen consiste a leur donner un nom. Dans la fenetre Writer, le nom de la section 
dans laquelle se trouve le curseur visible est affiche en bas a droite. Par programma- 
tion, une section se nomme avec sa propriete Name : 

maSection.Name = "Annexe 2" 



Piece Nom de section existant 

Si vous donnez par erreur a une section le nom d'une section existante, son nom ne sera pas modifie. Elle 
gardera le nom par defaut, Secti onl par exemple. 

Le document Writer tient a jour la collection de ses sections dans l'objet 
TextSections (attention au s). Un element de cette collection est accessible par son 
nom, avec les fonctions suivantes de l'objet collection : 

• hasByName(nom) renvoie True si une section existe avec ce nom, 

• getByName(nom) renvoie l'objet section de ce nom, ou declenche une erreur s'il 
n'existe pas. 

D'autre part, il est necessaire de se positionner dans la section. Pour se positionner au 
debut ou a la fin de la section, on utilise la propriete Start ou End de l'objet Anchor 
fourni par la section : 

' creer un curseur au debut de la section 

curseurS = monTexte . createTextCurso rBy Range (maSecti on .Anchor . Start) 
' deplacer le curseur a la fin de la section 
cu rseurS.gotoRange(maSecti on .Anchor . End) 
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Un positionnement a un endroit quelconque peut etre memorise par un signet (book- 
mark). Voyez ailleurs dans ce chapitre comment utiliser les signets. 

Nous avons cree dans un document exemple trois sections nominees. La macro sui- 
vante va ecrire dans chacune. 

rem Code08-15 . odt bibli : Sections2 Modulel 
Option Explicit 

Sub NaviguerDansSectionsO 

Dim monDocument As Object, monTexte As Object 

Dim cursA As Object, cursB As Object, cursC As Object 

Dim sectA As Object, sectB As Object, sectC As Object 

Dim lesSections As Object, prgr As Integer 

prgr = com . sun . star . text . Control Character . PARAGRAPH_BREAK 

monDocument = Thi sComponent 

monTexte = monDocument .Text 

lesSections = monDocument .TextSecti ons 

' il y aura une erreur si une des sections n'existe pas 

sectA = lesSections. getByName("Al i ne") 

sectB = lesSections .getByName("Brigitte") 

sectC = lesSections .getByName("Claudine") 

cursA = monTexte . createTextCursorByRange(sectA. Anchor .Start) 
cursB = monTexte. createTextCursorByRange(sectB. Anchor) 
cursC = monTexte . createTextCursorByRange(sectC. Anchor . End) 
monTexte. i nsertStri ng(cursA, "AAAA" , false) ' insere au debut 
monTexte. insertString(cursB, "BBBB", true) ' ecrase le texte 
monTexte. i nsertStri ng(cursC, "CCCC" , false) ' ajoute a la fin 
monTexte. insertControlCharacter(cursA, prgr, false) 
monTexte. insertControlCharacter(cursC, prgr, false) 
monTexte. i nsertStri ng(cursC, "DDDD" , false) 
print "Ef facer la section Brigitte !" 

cursB. gotoRange(sectB. Anchor , false) ' toute la section 
cursB. String = "" ' efface son contenu 

sectB. dispose' la section disparait, mais reste un paragraphe 
cursB.goLeft(l, true) 

cursB. String = "" ' supprime le paragraphe precedent 
End Sub 

L'insertion de BBBB ecrase tout le texte de la section, car le curseur cursB a ete initia- 
lise a la zone Anchor, ce qui equivaut a selectionner tout le texte de la section. 

La suppression complete d'une section demande un peu de gymnastique. D'abord, son 
contenu est supprime. Toute la zone est remplacee par une chaine de caracteres vide. 
En fait, il va rester une marque de paragraphe dans la section. Letape suivante consiste 
a supprimer l'objet section, en invoquant sa methode di spose. Elle ne supprime pas le 
texte correspondant (ici reduit a un paragraphe), qui devient un texte ordinaire, hors- 
section. Finalement, nous realisons l'equivalent de se positionner dans ce paragraphe 
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vide puis taper la touche Retour arriere. Si nous nous contentions de supprimer le para- 
graphe vide, c'est le paragraphe suivant qui deviendrait hors-section. 

Si cette macro ne vous a pas pose de probleme, alors vous maitrisez bien la gestion 
des curseurs... 

Proprietes des sections 

Les principales proprietes de section de texte sont listees dans le tableau 8-46. 
D'autres sont documentees dans l'API, voyez com. sun. star. text. TextSecti on. 

Tableau 8-46 Proprietes de section 



Name 


Stri ng 


Nom de la section. 


Fi 1 eLi nk 


Object 


Le contenu de la section est obtenu d'un autre document. 


Li nkRegi on 


Stri ng 


Nom d'une section ou d'un signet qui precise la zone de texte a utili- 
ser pour la section. 


Condition 


Stri ng 


Formule conditionnelle. 


IsVisible 


Bool ean 


Fal se rend la section invisible. 


IsProtected Boolean 


True pour proteger la section des modifications par I'utilisateur. 


ProtectionKey 


Array 


Mot de passe crypte, un octet par element. 


ParentSection 


Object 


La section parente de celle-ci, ou Nul 1 . 


ChildSections 


Array 


Tableau des sections incluses dans celle-ci, y compris les sous-sections. 



La propriete Condition est evaluee pour decider si la section doit etre invisible (si la 
propriete IsVi si bl e est Fal se). Si la propriete Condi ti on est une chaine vide, elle est 
consideree comme True. Les expressions conditionnelles sont expliquees dans l'aide 
en ligne de Writer, voyez Condition ; Champ. 

La protection effectuee par IsProtected peut etre annulee par I'utilisateur (utiliser le 
navigateur, clic droit sur la section, Editer). L'API ne permet pas d'appliquer un vrai 
mot de passe, mais vous pouvez faire ceci : 

Dim monSecret(2) As Integer 

monSecret(O) = 25 ' exemple de faux mot de passe crypte 

monSecret(l) = 26 

monSecret(2) = -32 

sectB . ProtectionKey = monSecretO 

sectB. IsProtected = true 
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Le tableau ProtectionKey contient normalement les octets du mot de passe crypte. 
Ici, l'utilisateur devra retrouver le mot de passe correspondant, que personne ne 
connait ! Vous cependant, en affectant Fal se a IsProtected, vous pouvez deproteger 
une section sans meme connaitre son mot de passe ! Pour supprimer le mot de passe, 
il suffit d'affecter a Protect! onKey un tableau vide. 

La propriete Fi 1 eLi nk est une structure composee de deux elements : 

• Fi 1 eURL, de type Stri ng, est l'adresse du document lie. 

• Fi 1 terName, de type Stri ng, est le nom du filtre eventuel necessaire pour charger 
le fichier. 

La propriete LinkRegion precise la zone de texte concernee dans le document lie. Si 
Fi 1 eLi nk est vide, la zone de texte est recherchee dans le document principal. 



Les styles 

Nous avons indique au chapitre 7 les elements communs a la gestion des styles. Nous 
abordons maintenant les styles propres aux documents Writer. 

Style de paragraphe 

Le style de paragraphe expose les proprietes de paragraphe ainsi que les proprietes de 
caractere, que nous avons deja vues plus haut a la section « Formatage ». Parmi les 
quelques proprietes specifiques au style, on peut retenir la propriete Fol 1 owStyl e, de 
type Stri ng, qui correspond a Style de suite dans l'interface utilisateur. 

Style de caractere 

Un style de caractere possede toutes les proprietes de caractere, plus celles du 
tableau 8-47. 

Tableau 8-47 Proprietes de style de caractere 





CharDiff Height 


Doubl e 


Difference de tail le, en points, du caractere par rapport au caractere parent. 


CharPropHeight 


Integer 


Hauteur du caractere en pourcentage de celle du caractere parent. Exemple : 
125 pour 125%. 



Manipuler les documents OpenOffice.org 

Troisieme partie 



Style de page 



Les proprietes de style de page comprennent, outre celles du tableau 8-48, des pro- 
prietes relatives a l'en-tete et au pied de page, qui sont decrites dans une section dediee. 

Tableau 8-48 Proprietes de style de page 



BackColor 


Long 


Couleurdu fond. 


BackTransparent 


Boolean 


True rend le fond transparent (interface utilisateur : 
sans remplissage). 


Follow/Style 


Stri ng 


Nom du style applique a la page inseree apres celle-ci. 


TopBorder 


Object 


Structure de la ligne de bordure du haut. Voir le tableau 8-8. 


TopBorderDi stance 


Long 


Espacement par rapport a la bordure du haut. 


BottomBorder 


Object 


Structure de la ligne de bordure du bas. Voir le tableau 8-8. 


BottomBorderDi stance 


Long 


Espacement par rapport a la bordure du bas. 


LeftBorder 


Object 


Structure de la ligne de bordure de gauche. Voir le tableau 8-8. 


LeftBorderDi stance 


Long 


Espacement par rapport a la bordure de gauche. 


RightBorder 


Object 


Structure de la ligne de bordure de droite. Voir le tableau 8-8. 


Ri ghtBorderDi stance 


Long 


Espacement par rapport a la bordure de droite. 


Shadow/Format 


Object 


Ombre portee. Voir le tableau 8-9. 


TopMargi n 


Long 


Marge du haut, en 1/100 de mm. 


BottomMargi n 


Long 


Marge du bas, en 1/100 de mm. 


LeftMargi n 


Long 


Marge de gauche, en 1/100 de mm. 


Ri ghtMargi n 


Long 


Marge de droite, en 1/100 de mm. 


IsLandscape 


Bool ean 


True si la page est en orientation Paysage 


Numberi ngType 


Integer 


Type de numerotation par defaut. Constante nommee, voir 

tableau 8-50. Valeur par defaut : 

com . sun . star . styl e . Numberi ngType .ARABIC 


PageStyleLayout 


Integer 


Indique quelles pages sont concernees. Constante nommee, voir 

tableau 8-49. Valeur par defaut : 

com . sun . star . styl e . PageStyl eLayout . ALL 


Pri nterPaperTray 


Stri ng 


Nom du bac de I'imprimante selectionnee. 


Width 


Long 


Hauteur de la page, en 1/100 de mm. 


Height 


Long 


Largeurde la page, en 1/100 de mm. 
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Tableau 8-49 Constantes de disposition de page 



ALL Pages gauches et droites. 


LEFT 


Pages gauches seulement. 


RIGHT 


Pages droites seulement. 


MIRRORED 


Les pages gauches utilisent ce style, les pages droites prennent des 
valeurs "en miroir". 


Tableau 8-50 Constantes de type de numerotation 




ARABIC 


1,2, 3,4 


CHARS_UPPER_LETTER 


A, B, C, D 


CHARS_LOWER_LETTER 


a, b, c, d 


ROMANLUPPER 


I, II, III, IV, V 


R0MAN_L0WER 


i, ii, iii, iv, V 


NUMBER_N0NE 


Pas de numerotation. 


CHARS_UPPER_LETTER_N 


A, B, Y, Z, AA, BB, CC, ... AAA, ... 


CHARS_LOWER_LETTER_N 


a, b, y, z, aa, bb, cc, ... aaa, ... 



Pour inserer dans un document des pages d'orientation differente ou ayant d'autres 
caracteristiques particulieres, il est recommande d'utiliser des styles de page appropries. 
Tous les styles de page sont bases sur le style Standard. Nous allons creer deux styles : 

• un style a orientation Portrait au format A4, qui est simplement une copie du 
style Standard ; 

• un style a orientation Paysage, lui aussi au format A4. 

La macro va creer les deux styles successivement. Dans le panneau Styles et formatage, 
basculer eventuellement l'affichage d'une famille de style a l'autre pour faire appa- 
raitre les nouveaux styles. 



rem Code08-07 . odt 
Option Explicit 



bibli : OrientationPages Modulel 



Sub CreerDeuxStylesPageO 
Dim monDocument As Object 

Dim lesFamilles As Object, uneFamille As Object 
Dim nouvStyle As Object 
monDocument = Thi sComponent 
lesFamilles = monDocument . Styl eFami 1 i es 
uneFamille = lesFamilles.getByName("PageStyles") 
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nouvStyl e = monDocument . createInstance("com . sun . star . styl e . PageStyl e") 

' creer un nouveau style identique au style Standard 
uneFamille. insertByName ("A4 Portrait", nouvStyle) 

nouvStyl e = monDocument . createlnstanceC'com . sun . star . styl e . PageStyl e") 
uneFamille. insertByName ("A4 Paysage" , nouvStyle) 

' creer un style Paysage 

nouvStyl e . Is Landscape = True 

nouvStyle. Width = 29700' hauteur 29,7 cm 

nouvStyle. Height = 21000' largeur 21,0 cm 

' ( par defaut le style de suite est le style en cours ) 

End Sub 

Pour chaque nouveau style, nous obtenons un objet style avec la fonction 
createlnstance de 1' objet document. Apres adaptation eventuelle, ce style est insere 
dans sa famille par la methode insertByName. 

Remarquez qu'avec le format Paysage nous avons aussi change la hauteur et la lar- 
geur, alors qu'avec l'interface utilisateur un simple clic sur le bouton Paysage suffit a 
intervertir ces deux valeurs. 

Nous disposons maintenant de deux nouveaux styles, A4 Portrait et A4 Paysage. 
Nous allons les utiliser dans la macro suivante, qui va aj outer plusieurs pages a un 
document existant, qui n'utilise au depart que des pages de style Standard. 

rem Code08-07.odt bibli : Ori entati onPages Module2 
Option Explicit 

Sub AjouterPagesO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object 

Dim PageAvant As Integer, paragr As Integer 

paragr = com . sun . star . text . Control Character . PARAGRAPH_BREAK 

PageAvant = com . sun . star . styl e . BreakType . PAGE_BEFORE 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

monCurseur = monTexte. createTextCursor 

With monCurseur 

.gotoEnd(False) 
' ajouter un paragraphe 

monTexte. insertControlCharacter(monCurseur, paragr, false) 

. PageDescName = "A4 Paysage"' provoque un saut de page 
monTexte. insertString(monCurseur, "Style A4 Paysage", false) 
monTexte. insertControlCharacter(monCurseur, paragr, false) 

.breakType = PageAvant' insere un saut de page AVANT 
monTexte. insertString(monCurseur, "Style A4 Paysage", false) 
monTexte. insertControlCharacter(monCurseur, paragr, false) 
.PageDescName = "Standard" ' provoque un saut de page 
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monTexte.insertString(monCurseur, "Style Standard", false) 
monTexte.insertControlCharacter(monCurseur, paragr, false) 

. PageDescName = "A4 Portrait"' provoque un saut de page 
monTexte.insertString(monCurseur, "Style A4 Portrait", false) 
monTexte.insertControlCharacter(monCurseur, paragr, false) 

End With 

End Sub 

Nous allons en fin de document pour ajouter un paragraphe. En modifiant la pro- 
priete PageDescName du curseur, nous affectons le style de page A4 Paysage a partir 
de la position du curseur. Ceci provoque un saut de page. 

Nous inserons un texte, puis un nouveau paragraphe dans cette page Paysage. La pro- 
priete BreakType insere un saut de page ordinaire, mais comme le style de page de suite 
est le meme, nous restons en Paysage. Nous inserons encore un texte et un paragraphe. 

Un nouveau changement de la propriete PageDescName nous fait revenir au style de 
page Standard, done en orientation Portrait avec un nouveau saut de page. Nous 
inserons encore un texte et un paragraphe. 

Enfin, nous changeons le style de page en A4 Portrait qui n'est qu'une copie du 
style Standard. Cela provoque neanmoins un nouveau saut de page. 

Astuce 

Sur un document, vous pouvez facilement verifier le style de la page oil se trouve le curseur visible : il est 
affiche en bas de la fenetre Writer, a cote de I'indicateur de numero de page. 



Les en-tetes et pieds de page 

Les en-tetes et pieds de page ne sont pas des elements ordinaires du document. En effet, 
ils sont des elements appartenant a un style de page, par defaut le style de page Standard. 
Pour faire apparaitre ou pour modifier un en-tete ou pied de page, il faut retrouver le style 
de page de la page qui nous interesse et le modifier. En consequence, toutes les pages du 
meme style subiront la meme modification d'en-tete ou pied de page. 

Nous allons inserer un en-tete dans la premiere page d'un document (et celles qui ont 
le meme style). 

rem Code08-07 . odt bibli : Haut_Bas Modulel 
Option Explicit 

Sub InsererUnEnTeteO 
Dim monDocument As Object 

Dim monTexte As Object, monCurseur As Object 
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Dim Texte2 As Object, Curseur2 As Object 

Dim nomStyl eMaPage As String, StyleMaPage As Object 

Dim lesStylesPage As Object 

monDocument = Thi sComponent 

monTexte = monDocument. Text 

monCurseur = monTexte . createTextCursor 

' recuperer le nom du style de page en cours 

nomStyl eMaPage = monCurseur . PageStyl eName 

print "Cette page est du style : " & nomStyl eMaPage 

' recuperer la collection de styles de pages 

1 esStyl esPage = monDocument . Styl eFami 1 ies . getByName ("PageStyl es") 

' recuperer le style de la page en cours 

Styl eMaPage = 1 esStyl esPage . getByName (nomStyl eMaPage) 

With StyleMaPage 

.HeaderlsOn = true ' inserer un en-tete 

.HeaderBodyDi stance = 1000 ' 10 mm 

.HeaderHeight = 2500 ' 25mm 

Texte2 = .HeaderText' zone de texte de 1 'en-tete 
End With 

Curseur2 = Texte2 . createTextCursor ' curseur dans 1 'en-tete 
' ecrire un texte dans 1 'en-tete 

Texte2 . i nsertStri ng(Curseur2 , "Voici un en-tete", false) 
End Sub 

Nous voyons encore un exemple ou l'usage d'un document modele avec des styles 
bien definis peut alleger considerablement l'ecriture de macros en evitant de creer ou 
modifier les en-tetes ou bas de page. 

L'objet style de page expose un tres grand nombre de proprietes pour l'en-tete (Header) 
et pour le pied de page (Footer). Comme ces proprietes sont similaires, le tableau 8-51 
ne listera que les principales proprietes de l'en-tete, sachant qu'il suffit de remplacer 
Header par Footer dans le nom de propriete pour obtenir celles du pied de page. 



Tableau 8-51 Proprietes d'en-tete de page 



HeaderlsOn 


Bool ean 


True si un en-tete est active. 


HeaderlsShared 


Boolean 


True si les en-tetes gauche et droite sont identiques. 


HeaderBackColor 


Long 


Couleur du fond. 


HeaderBackTran spa rent 


Boolean 


True rend le fond transparent (interface utilisateur : sans 
remplissage). 


HeaderLeftBorderDi stance 


Long 


Distance entre marge et bord gauche de l'en-tete, en 1/100 
de mm. 


HeaderRightBorderDi stance 


Long 


Distance entre marge et bord droit de l'en-tete, en 1/1 00 
de mm. 
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Tableau 8-51 Proprietes d'en-tete de page (suite) 



HeaderTopBorderDi stance 


Long 


Distance entre marge et bord du haut de I'en-tete, en 1/100 
de mm. 


HeaderBottomBorderDi stance 


Long 


Distance entre marge et bord du bas de I'en-tete, en 1/100 
de mm. 


HeaderBodyDi stance 


Long 


Distance entre en-tete et texte principal, en 1/100 de mm. 


HeaderHeight 


Long 


Hauteur de I'en-tete, en 1/100 de mm. 


Heade rShadowFormat 


Object 


Ombre portee. Voir le tableau 8-9. 


Heade rText 


Object 


Zone du texte, si les en-tetes gauche et droite sont 
identiques. 


HeaderTextLeft 


Object 


Zone du texte de I'en-tete gauche. 


HeaderTextRight 


Object 


Zone du texte de I'en-tete droite. 


HeaderLeftMargi n 


Long 


Marge gauche de I'en-tete. 


HeaderRi ghtMargi n 


Long 


Marge droite de I'en-tete. 


Header Left Border 


Object 


Structure de la ligne de bordure gauche. Voir le tableau 8-8. 


HeaderRi ghtBorder 


Object 


Structure de la ligne de bordure droite. Voir le tableau 8-8. 


HeaderTopBorder 


Object 


Structure de la ligne de bordure du haut. Voir le tableau 8-8. 


Heade rBottomBorder 


Object 


Structure de la ligne de bordure du bas. Voir le tableau 8-8. 



Style de cadre 

Les proprietes de style de cadre reprennent la plupart des proprietes d'un cadre. 



Style de numerotation 

Les proprietes de style de numerotation sont constitutes d'elements « a tiroirs » qu'il 
serait trop long de decrire dans ce livre. Veuillez consulter la documentation API sur 
les services suivants : 

• com. sun. star. text. Numberi ngRul es ; 

• com . sun . star . text . Numberi ngLevel . 



Les champs de texte 



II s'agit des differents champs qu'on insere manuellement par le menu lnsertion> 
Champs. II existe de nombreux types de champs. Chacun est fourni par un service spe- 
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cifique, qui inclut le service de base com. sun. star. text. TextFi eld. Les caracteristi- 
ques de chaque type de champ sont documentees dans les modules de l'API : 

• com. sun. star. text. textfi eld 

• com. sun. star. text. FieldMaster 



Ressources 

Une presentation exhaustive est donnee dans le Developer's Guide a la section Text Documents>Wor- 
king with Text Documents>Text Fields. 



Chaque TextFi eld a ses proprietes, qui ne sont pas toujours evidentes. Pour les 
champs contenant un nombre (champ Date, champ Heure, champ Nombre de pages, 
champ Util i sateur, etc.), le format d'affichage depend de la propriete 
NumberFormat, de type Long. Cette valeur est un index dans la collection des formats 
disponibles dans le document. Ce concept est decrit au chapitre 7 a la section « Les 
formats de nombre ». 

Certains champs TextFi eld sont accessibles directement, d'autres dependent d'un 
champ maitre (en anglais, FieldMaster). Pour illustrer les principes generaux, nous 
debuterons avec des champs de texte simple : FileName, Notes. Puis, nous aborde- 
rons les champs dependant d'un champ maitre : variable de champ utilisateur ; 
champ de base de donnees. Nous terminerons cette section avec les champs de para- 
graphe masque et de texte conditionnel, car leur condition depend en general de la 
valeur d'une variable utilisateur. 



Bogues 

En revisant cette section nous avons detecte plusieurs bogues mineurs affectant les champs de texte. II 
est fort probable qu'il y en ait d'autres. Une premiere anomalie concerne le nom des services de champs 
de texte. Avec la version 1 d'OpenOffice.org, ces noms etaient incorrects. Depuis la version 2, ces noms 
ont ete corriges, par exemple : 

• En V1 : com. sun. star. text. TextField. FileName 

• A partir de V2 : com . sun . star . text . text field . Fi 1 eName 

Pour des raisons de compatibilite, les anciens noms ont ete laisses en double. Dans nos codages, nous 
utilisons les noms actuels. 



Le champ de texte FileName 

Les champs texte, ou TextField, sont obtenus avec la fonction createlnstance de 
l'objet document, puis inseres avec la methode i nsertTextContent de l'objet texte 
apres avoir rempli les proprietes. Lexemple qui suit insere dans le document Writer 
le nom de son fichier. On utilise pour cela le service textfi el d . Fi 1 eName. 
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rem Code08-13 . odt bibli : ChampsTexte Modulel 
Option Explicit 

Sub AjouterChampTexteO 

Dim monDocument As Object, monTexte As Object, monCurseur As Object 

Dim leChamp As Object 

monDocument = ThisComponent 

monTexte = monDocument .Text 

monCurseur = monTexte . createTextCursor 

monCurseur .gotoEnd (False) 

1 eChamp=monDocument . c reatelnstance ( "com . sun . star . text . textf iel d . Fi 1 eName") 
leChamp.IsFixed = False ' le champ se mettra a jour automatiquement 
leChamp.FileFormat = 2 ' afficher le nom du fichier sans son extension 

monTexte. insertTextContent (monCurseur, leChamp, False) 
End Sub 

Si la propriete IsFixed du champ recoit la valeur True, le contenu du champ restera 
inchange si on renomme ou deplace le fichier. Si la propriete recoit la valeur Fal se, le 
contenu du champ se mettra a jour automatiquement pour refleter le nom et chemin 
actuels du fichier. 

La propriete File Format recoit une constante dont les valeurs possibles sont listees 
au tableau 8-52. Un bogue fait que, pour un meme format, la valeur depend de l'etat 
de la propriete IsFixed ; c'est pourquoi le tableau donne deux series de valeurs au 
lieu des constantes decrites dans la documentation de l'API. 



Tableau 8-52 Constantes de FileFormat 





Le nom complet avec le chemin. 


0 


1 


Le chemin seulement. 


1 


2 


Le nom seulement, sans I'extension. 


2 


3 


Le nom du fichier avec I'extension. 


3 


0 



Le champ de note 

Les notes sont des textes inseres au fil du texte, par le menu lnsertion>Note. Depuis la 
version 3.0, elles apparaissent en marge de la fenetre du document et il est possible 
d'en formater le texte. Du point de vue de l'API, les notes sont des TextFi el d. Leurs 
proprietes specifiques sont indiquees au tableau 8-53. 



Manipuler les documents OpenOffice.org 

Troisieme partie 



Tableau 8-53 Proprietes d'un champ de note 



Author 


Stri ng 


Nom de I'auteur de la note. 


Date 


Object 


Date de la note, structure UNO (voir index, structure Date). 
Obsolete depuis la version 3.0. 


DateTimeVal ue 


Object 


Date et heure de la note, structure UNO (voir index, structure 
DateTime). 


Content 


Stri ng 


Texte de la note sous forme de chame de caracteres. 


TextRange 


Object 


Objet texte de la note. 


Anchor 


Object 


Position d'insertion de la note. 



Nous allons ajouter un texte dans un document, et y inserer une note. 

rem Code08-13 .odt bibli : ChampsTexte Module2 
Option Explicit 

Sub AjouterNoteO 

Dim monDocument As Object, monTexte As Object, monCurseur As Object 

Dim maNote As Object, uneDate As New com. sun. star. util .DateTime 

Dim texteNote As Object, curseurNote As Object 

monDocument = Thi sComponent 

monTexte = monDocument .Text 

monCurseur = monTexte. createTextCursor 

monCurseur .gotoEnd(fal se) 



monTexte. insertString(monCurseur, "Ce paragraphe contient ", False) 

maNote = monDocument . createInstance("com . sun . star . text . textf iel d .Annotation") 

maNote .Author = "Arthur Duchemin" ' auteur de la note 

uneDate. Day = 15 

uneDate. Month = 7 

uneDate. Year= 2008 

uneDate. Hours = 15 

uneDate .Minutes = 52 

maNote. DateTimeVal ue = uneDate ' imposer la date-heure de la note 

texteNote = maNote .TextRange 

curseurNote = texteNote. createTextCursor 

curseurNote. CharWeight = com. sun. star. awt.FontWeight. BOLD 

texteNote. i nsertStri ng(curseurNote , "Attention !", False) 

texteNote. i nsertStri ng(curseurNote , chr(10), False) ' nouvelle ligne 

curseurNote. CharWeight = com. sun. star. awt.FontWeight. NORMAL 

curseurNote. CharColor = RGB(200, 0, 0) 

texteNote. i nsertStri ng(curseurNote , "Ce texte est un exemple.", False) 



Les documents Writer 

Chapitre 8 



monTexte. insertTextContent(monCurseur, maNote, False) 
monTexte."insertStn'ng(monCurseur, "une note inseree", False) 
End Sub 

Tout d'abord, nous utilisons un curseur d'ecriture pour nous positionner dans le 
document, puis inserer un texte. La note sera inseree grace a lui comme nous l'avons 
vu pour les autres champs de texte. La methode createlnstance, invoquant le ser- 
vice TextField. Annotation, nous donne une note vierge attachee a notre document ; 
reste a la remplir. 

La propriete Author doit etre remplie avec le nom de l'auteur de la note. 

Si la propriete DateTi meVal ue nest pas initialisee, OpenOffice.org utilisera la date et 
heure au moment de l'insertion de la note. Avant la version 3.0, seule la propriete 
Date existait, que Ton remplissait avec une structure Date, sans indication d'heure. 
Depuis la version 3.0 il est preferable d'utiliser la nouvelle propriete DateTi meVal ue, 
qui recoit une structure DateTi me. 

La propriete TextRange nous donne acces a un objet texte simplifie, a partir duquel 
nous pouvons creer un curseur qui nous permet d'ecrire un texte formate. La notion 
de paragraphe n'existe pas dans les notes. Pour aj outer une ligne, il suffit done 
d'inserer un caractere « saut de ligne ». Le curseur d'ecriture n'offre que peu de 
methodes de deplacement, essentiellement gotoStart, gotoEnd, goLeft, goRight. 
Ecrire un texte non formate est plus simple, il suffit de mettre la chaine de caracteres 
dans la propriete Caption. 

Une fois ces renseignements fournis, nous pouvons inserer la note, comme tout ele- 
ment de texte, par i'intermediaire de la methode i nsertStri ng en utilisant le curseur 
defini sur le texte principal. Naturellement, on peut continuer le texte apres la note. 

Depuis la version 3.1 d'OpenOffice.org, le lecteur du document peut repondre a une 
note. Sa reponse est vue comme une autre note inseree au meme endroit. 

PlEGE Les notes dans un texte 

Si vous explorez un texte, une note compte comme un caractere dans le texte. Soyez vigilant lors du 
deplacement de vos curseurs. 



Retrouver une note 

La collection TextFields memorise tous les champs de texte du document, dont les 
notes font partie. Pour acceder aux objets de cette collection, on doit effectuer une 
boucle d'enumeration, et reconnaitre dans les objets obtenus la note a traiter. II est 
possible de recourir au meme principe pour d'autres types de champs de texte. La 
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macro ci-apres efface toutes les notes d'un auteur specifique. Notez qu'une selection 
sur la date serait egalement possible. 

rem Code08-13 .odt bibli : ChampsTexte Module3 
Option Explicit 

Sub EffacerNotesAuteur() 

Dim monDocument As Object, lesChamps As Object, unChamp As Object 
monDocument = Thi sComponent 

lesChamps = monDocument. TextFields.createEnumeration 
Do While lesChamps. hasMoreElements 
unChamp = lesChamps. NextElement 

i f unChamp . supportsServi ce ("com . sun . star . text . text fi el d .Annotation") then 
if unChamp. Author = "Arthur Duchemin" then 
MsgBox(unChamp. Content, 0, "Texte de la note a supprimer") 
unChamp. dispose 
endif 
endif 
Loop 
End Sub 

Nous commencons par creer 1'enumeration des objets Text Field en appelant la 
methode createEnumeration de la collection TextFields qui nous permettra d'exa- 
miner tous les champs (TextField). Ceux-ci pouvant etre autre chose que des notes, 
nous testons pour chacun s'il supporte le service textfi eld. Annotation par l'inter- 
mediaire de sa methode supportsServi ce. 

Si c'est le cas, un test sur sa propriete Author nous indique si cette note est candidate 
a la suppression. Dans l'affirmative, nous affichons le texte de la note, puis l'appel de 
la methode di spose de l'objet TextFi el d permet de la supprimer. 

De la meme maniere, on pourrait retrouver une note pour la modifier. Cependant, 
Tissue 100374 signale que la modification du texte n'est pas possible dans les 
versions 3.0 et 3.1, la correction est prevue avec la version 3.2. 

La propriete Anchor d'une note renvoie un objet permettant de savoir dans quelle 
zone de texte est inseree la note : dans le texte principal, dans un cadre, dans une cel- 
lule de tableau, dans un pied de page, etc. La methode est identique a celle exposee 
plus haut dans la section « Ou se trouve le curseur ? », en employant l'objet obtenu 
par Anchor aulieu de curseurVisible. 



Les champs dependant d'un champ maitre 

Le principe est de definir un champ d'une famille particuliere, en lui donnant un 
nom et une valeur, et de le rajouter a la liste des champs de texte maitre (ou 
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TextFi el dMaster). Le champ texte visible dans le document sera alors lie a ce champ 
maitre. On pourra creer autant de TextFi eld dependant de ce TextFi el dMaster que 
necessaire. Si la valeur doit etre mise a jour, il suffira de modifier le champ maitre. 

Manipuler ces champs se fait done en trois etapes : 

1 Creer un champ maitre avec un nom arbitraire. 

2 Creer et inserer des champs dependants du champ maitre. 

3 Donner une valeur au champ maitre, ou la modifier. 

Nous nous interesserons a deux families de champs maitres : User (variable champ 
d'utilisateur) et Database (champ de base de donnees). 

Variables champ d'utilisateur 

Un champ utilisateur peut etre considere comme une variable du document, affichee 
ou non. Vous pouvez voir ces champs dans l'onglet Variable du panneau d'insertion de 
champs. 

L'exemple se compose de quatre macros dans le meme module Basic, qui se parta- 
gent deux constantes. II est possible de lancer chaque macro separement. 

Creer un champ maitre 

La macro suivante cree un champ maitre ayant pour nom NomDuProduit. 

rem Code08-13 . odt bibli : ChampsTexte Module4 
Option Explicit 

Private Const racine = "com . sun . star . text . Fiel dMaster" 
Private Const nomChamp = "NomDuProduit" 

Sub creerChampMaitreO 

Dim leDoc As Object, lesMaitres As Object, monMaitre As Object 

leDoc = Thi sComponent 

lesMaitres = leDoc. TextFiel dMasters 

If 1 esMai tres . hasByName(raci ne & ".User." & nomChamp) then 

MsgBox("Ce champ maitre existe deja", 16) 
el se 

monMaitre = 1 eDoc . createlnstance(raci ne & ".User") 

monMaitre. Name = nomChamp 
end if 
End Sub 

Pour alleger le code, nous declarons une constante appelee racine, qui est la chaine 
de caracteres commune a tous les champs maitres. De meme, le nom de notre 
variable utilisateur sera lui aussi mis dans une constante appelee nomChamp ; e'est le 
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nom qui apparait dans l'interface utilisateur. Evitez un nom contenant des mots 
separes ou avec des accents, cela produit des anomalies. Ces deux constantes seront 
utilisees dans les macros du meme module Basic. 

La collection des champs maitres TextFieldMasters est accessible depuis l'objet 
document. Elle possede la methode hasByName permettant de controler si le champ 
que nous desirons creer n'existe pas deja. En effet, une exception - done une erreur 
de la macro - est levee si Ton tente d'inserer une champ maitre portant un nom deja 
existant. L'appellation d'un nom de champ maitre pour variable utilisateur est consti- 
tute de sa racine (notre constante racine), d'un point separateur, du terme User, 
d'un autre point separateur, et du nom de la variable, ici represente par la constante 
nomChamp, ce qui aboutit dans notre cas a un champ maitre nomme : 

com. sun . star . text . Fi eldMaster . User . NomDuProdui t 

C'est cette valeur qui doit etre controlee. Notez que le nom du champ est reconnu 
independamment de la casse (par exemple nomduproduit). Si ce champ maitre 
n'existe pas, nous creons, avec createlnstance, un exemplaire de champ maitre con- 
teneur, done un MasterField de la famille User, soit : 
com. sun. star. text. FieldMaster. User. Nous obtenons done monMaitre, un champ 
maitre de type User. Pour le personnaliser, il suffit de le nommer en utilisant sa pro- 
priete Name. La propriete Name ne peut alors plus etre modifiee. 

Inserer un champ utilisateur 

Une fois notre champ maitre cree, nous insererons un exemplaire de champ utilisa- 
teur dans le document, comme nous le ferions avec l'interface utilisateur. Nous allons 
l'inserer a la fin du document avec la macro insererChampUtilisateur. On peut 
l'executer plusieurs fois, effectuant ainsi plusieurs insertions dans le texte du docu- 
ment. Nous reproduisons ici la partie interessante de la macro, les variables ont la 
meme signification que precedemment. 

monMaitre = 1 esMai tres . getByName(raci ne & ".User." & nomChamp) 

1 eChamp = 1 eDoc . createlnstance ("com . sun . star . text . textf iel d . User") 

1 eChamp . attachTextFiel dMaster (monMai tre) 

leTexte = 1 eDoc. Text 

leCurseur = leTexte. createTextCursorO 

1 eCurseur . gotoEnd(Fal se) 

leTexte. insertStringOeCurseur, "Nouveau ! ", False) 

leTexte. insertTextContent (leCurseur, 1 eChamp, false) 

leTexte. -insertStringOeCurseur, ", une blancheur eclatante !", False) 

1 eDoc. TextFi elds. refreshQ 
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Nous recuperons le champ maitre (que nous venons de creer avec la macro prece- 
dente) avec la methode getByName de la collection TextFieldMasters du document. 
La methode createlnstance du document permet de creer un exemplaire de champ 
texte du meme type que celui du champ maitre que nous voulons utiliser ; dans notre 
cas : User. L'objet TextField a utiliser est fourni par le service 
com. sun. star. text. TextField. User. A present, nous disposons d'un objet 
TextField vierge, qui constitue un genre de modele. II nous faut l'associer a un 
champ maitre en utilisant sa methode attachTextFieldMaster, l'argument de la 
methode etant l'objet monMaitre que nous avons recupere auparavant. 

Apres avoir obtenu un curseur d'ecriture et l'avoir positionne en fin de document, 
nous ecrivons un texte. Maintenant, il nous suffit d'inserer leChamp dans le docu- 
ment en utilisant la methode insertTextContent de l'objet texte du document 
comme nous l'avons vu precedemment. 

Format d'aff ichage 

Si le champ maTtre est destine a contenir un nombre, on peut fixer, pour chaque champ utilisateur insere, 
le format d'affichage du nombre en utilisant la propriete NumberFormat de ce champ. 

Nous ajoutons un texte apres le champ. Les champs du document doivent etre 
ensuite reactualises en utilisant la methode TextFields. refresh pour que les chan- 
gements soient pris en compte. 

Modifier un champ maitre 

Nous aurions pu donner une valeur au champ maitre juste apres sa creation, puis 
inserer les champs utilisateurs dans le document. Ici nous faisons l'inverse : tout 
l'interet du champ maitre est que nous pouvons modifier la valeur qui lui est affectee. 
Ce changement sera repercute sur tous les champs utilisateurs du document qui y 
font reference. Void la partie interessante de la macro 
modi f i erContenuChampMai tre : 

monMaitre = lesMaitres . getByName (racine & ".User." & nomChamp) 
monMai tre .Content = "Lessive Blanco" 
'monMaitre. Value = 123.45E26 
leDoc.TextFields. refresh() 

La propriete Content du champ maitre sert a memoriser une chaine de caracteres. 
En utilisant a sa place la propriete Value, de type Double, nous pourrions memoriser 
un nombre. N'oubliez pas d'utiliser la methode refresh pour mettre a jour les 
champs dans le document. 
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Supprimer un champ maitre 

L'interface utilisateur permet de supprimer un champ maitre a condition qu'il n'existe 
plus aucun champ utilisateur de ce nom dans le document. Cette contrainte n'existe pas 
avec l'API. La macro supprimerChampMaitre supprimera le champ maitre ainsi que 
tous les champs utilisateurs qui y font reference. Void la partie importante de la macro : 

if" lesMaitres.hasByName(racine & ".User." & nomChamp) then 

monMaitre = 1 esMai tres . getByName(raci ne & ".User." & nomChamp) 
monMai t re . di spose 

end "if 

Si le champ maitre du nom cherche existe bien, on le recupere pour executer sa 
methode di spose, qui le supprime ainsi que les champs utilisateurs qui en dependent. 

Champ de base de donnees 

Comme nous le verrons au chapitre 12, l'API permet de manipuler des sources de 
donnees et d'acceder a des champs issus de requetes ou de tables de bases de donnees. 

L'interface utilisateur permet d'inserer les champs de ces sources de donnees en vue 
de publipostage, par exemple. Sans rentrer dans le detail des sources de donnees, 
nous indiquons ici comment inserer un tel champ au moyen de l'API, le processus 
etant tres voisin de celui d'un champ utilisateur. 

rem Code08-13 . odt bibli : ChampsTexte Modules 
Option Explicit 

Sub i nsererChampBaseO 

Dim leDoc As Object, leCurseur As Object 

Dim leChampMaitre As Object, leChamp As Object 

leDoc = thi sComponent 

Const racineChampMaitre = "com . sun . star . text . Fiel dMaster .Database" 
leChampMaitre = 1 eDoc . createlnstance(raci neChampMai tre) 

leChampMaitre.DataBaseName = "Bibliography" 
leChampMaitre.DataTableName = "biblio" 
leChampMaitre.DataColumnName = "Identifier" 

1 eChamp = 1 eDoc . createInstance("com . sun . star . text . textf iel d . Database") 
1 eChamp . attachTextFiel dMaster (1 eChampMai t re) 

leCurseur = leDoc. Text. createTextCursorO 
1 eCu rseur . gotoEnd (Fal se) 

leDoc. Text. i riser tTextContent (leCurseur, 1 eChamp, false) 
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1 eDoc . Textfi el ds . refresh () 
End Sub 

Un champ de base de donnees depend d'un champ maitre de type Database. 

L'exemplaire de champ que nous obtenons par createlnstance presente trois pro- 
prieties que nous devons renseigner : 

• DataBaseName : le nom de la source de donnees ; 

• DataTabl eName : le nom de la table concernee ; 

• DataCol umnName : le nom du champ dans la table. 

Le champ maitre est alors entierement defini et porte le nom : 

com . sun . star . text . Fi el dMaster . Database . Bi bl i ography . bi bl i o . Identi f i er 

De meme que precedemment, nous pouvons alors inserer, a l'aide de 
createlnstance, un champ TextField de la meme famille que le TextFi el dMaster 
que nous avons defini, a savoir com. sun. star. text, textfi eld. Database, etlui atta- 
cher l'objet TextFi el dMaster que nous avons cree pour notre champ de source de 
donnees, a l'aide de la methode attachTextFi el dMaster. 

Le champ peut ensuite etre insere dans le document. Nous appelons enfin la 
methode refresh de la collection TextFi elds pour mettre a jour le document. En 
pratique, un tel document est utilise ensuite dans le cadre d'un publipostage, ou il 
servira de modele pour creer autant de documents que de destinataires du publipos- 
tage, en exploitant les resultats d'une requete sur la base de donnees. 



Champ masque 

II s'agit du champ de paragraphe masque et du champ de texte masque Avec l'interface 
utilisateur, on les insere depuis l'onglet Fonctions du panneau d'insertion de champs. 
Rappelons que le masquage ne sera effectif qua la condition de ne pas cocher les cases 
Champs : texte masque et Champs : paragraphes masques dans Outils>Options>OpenOf- 
fice.org Writer>Aides au formatage. Par consequent, ne vous servez pas des textes et 
paragraphes conditionnels pour cacher une information confidentielle. 

Dans le document exemple, nous avons cree une variable utilisateur nominee Facture. 
Vous pourrez en changer la valeur par l'interface utilisateur. Une phrase du texte affiche 
le contenu de cette variable. La macro suivante ajoute deux paragraphes en fin de texte, 
le premier restant masque si la facture fait moins de 1 000 euros. Le champ paragraphe 
masque est obtenu en utilisant le service textfi el d . Hi ddenParagraph. 

rem Code08-13.odt bibli : ChampsTexte Module6 
Option Explicit 
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Sub insererParagrapheMasqueO 

Dim leDoc As Object, leCurseur As Object, leChamp As Object 
Dim finparagr As Long, leTexte As Object 

finParagr = com. sun. star. text. Control Character.PARAGRAPH_BREAK 

leDoc = Thi sComponent 

leTexte = leDoc. Text 

leCurseur = leTexte. createTextCursor() 

leCurseur.gotoEnd (False) 

1 eChamp=l eDoc . createInstance("com . sun . star . text . text fi el d . HiddenParagraph") 
leChamp. Condition = "Facture < 1000" 

leTexte. insertControlCharacter(leCurseur, finParagr, False) 
leTexte. insertTextContent (leCurseur, leChamp, false) 
leTexte. insertString(leCurseur, 

" Profitez de nos conditions de credit !", False) 
leTexte. insertControlCharacter(leCurseur, finParagr, False) 
leTexte. insertString(leCurseur, "Veuillez agreer, ", False) 
leDoc. TextFields. refresh() 'Rafraichir les champs - touche F9 
if leChamp. IsHidden then 

MsgBox("Condition real i see. Le paragraphe est cache.") 
else 

MsgBox("Condition non realisee. Le paragraphe est visible.") 
end if 
End Sub 

La propriete Condition contient une expression qui sera evaluee a True ou False, 
selon que la condition est realisee ou non. Le paragraphe sera masque si la condition 
vaut True. Lexpression peut comporter des operateurs arithmetiques, des fonctions 
mathematiques, etc. Les operateurs de comparaison sont listes au tableau 8-54. 



Attention 

Les operateurs d'egalite et d'inegalite ne sont pas ceux de Basic. 



Tableau 8-54 Evaluation de condition : comparaisons 
Resultat 





A == B 


True si A est strictement egal a B 


! = 


A != B 


True si A est different de B 


< 


A < B 


True si A est strictement inferieur a B 


<= 


A <= B 


True si A est inferieur ou egal a B 


> 


A > B 


True si A est strictement superieur a B 


>= 


A >= B 


True si A est superieur ou egal a B 
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Les nombres reels doivent etre ecrits en respectant le separateur decimal de la locali- 
sation (qui en France est la virgule). Rappelons que le test d'egalite entre deux varia- 
bles ou expressions en nombres reels n'a pas de sens a cause des inevitables erreurs de 
conversions et de calculs. Dans une expression, une chaine de caracteres doit etre 
encadree de guillemets, eux-memes doubles s'ils sont dans une instruction en Basic : 

leChamp. Condition = "Poete == ""Ronsard""" ' Poete est une variable 

Nous inserons une fin de paragraphe pour demarrer un nouveau paragraphs Le 
champ paragraphe masque est ensuite insere par la methode insertTextContent. 
Apres avoir ajoute une nouvelle fin de paragraphe, nous ajoutons un texte ordinaire, 
qui sera done toujours affiche, puisqu'il ne fait pas partie du paragraphe masque. 

Une fois le ou les champs inseres, les champs du document doivent etre reactualises 
par la methode refresh, ce qui permettra le calcul des conditions et la mise en page 
au niveau de l'interface utilisateur. La propriete IsHidden sert a connaitre le dernier 
etat de la condition de masquage. Lorsqu'on change la valeur de la variable utilisee 
par la condition, la mise a jour de l'affichage n'est pas instantanee, il faut eventuelle- 
ment actualiser les champs. 

Linsertion d'un texte masque est tres similaire. On utilise le service 
textfield.HiddenText et les proprietes Condition et IsHidden. Le texte a masquer 
conditionnellement est defini dans la propriete Content. Ce texte est une chaine de 
caracteres et non un objet texte au sens de l'API. Le formatage a l'interieur de cette 
chaine est impossible, e'est le formatage du champ lui-meme qui sera applique. 

Champ de texte conditionnel 

Ce type de champ permet d'afficher une chaine de caracteres ou une autre suivant la 
valeur True ou Fal se d'une condition. La macro qui suit, qu'il est amusant d'executer 
apres celle du paragraphe masque, affiche un texte plus aimable si la facture atteint au 
moins 10 000 euros. 

rem Code08-13.odt bibli : ChampsTexte Module7 
Option Explicit 

Sub insererTexteConditionnel () 

Dim leDoc As Object, leCurseur As Object, leChamp As Object 
leDoc = ThisComponent 
leCurseur = leDoc. Text. createTextCursor() 
leCurseur.gotoEnd( False) 

1 eChamp = 1 eDoc . createInstance("com . sun . star . text . textf iel d . Condi tional Text") 
leChamp. Condition = "Facture >= 10000" 
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leChamp.TrueContent= "tres honorable client, etc" 
leChamp.FalseContent = "cher client, etc" 
leDoc.Text.insertTextContent(leCurseur, leChamp, false) 

leDoc.TextFields.refreshO 'Rafraichir les champs - touche F9 

if not leChamp.IsConditionTrue then ' ce codage tient compte du bogue ! 

MsgBox("Condition real i see.") 
else 

MsgBox("Condition non real i see.") 
end if 
End Sub 

Ici, le service est textfi eld. Conditional Text, on retrouve la propriete Condition. 
Nous devons remplir avec des chaines de caracteres les proprietes TrueContent et 
FalseContent qui correspondent respectivement aux textes a afficher si la condition 
est remplie ou non. Le champ est insere par la methode insertTextContent, et les 
champs reactualises. 

La propriete IsCondi ti onTrue est mal nommee : elle renvoie la valeur True quand la 
condition n'est pas realisee, False quand elle est realisee ! Le contournement de ce 
bogue (Issue 99996) est facile : il faut utiliser l'operateur de negation not. 



Les signets et renvois 

Un signet (en anglais, bookmark) est un repere dans le texte. Manuellement, vous 
inserez un signet a l'endroit du curseur visible avec le menu lnsertion>Repere de 
texte.. .>nomDuSignet. Un signet peut aussi designer une zone de texte ; il suffit quelle 
soit selectionnee quand on definit le signet. 

Utiliser un signet existant 

Vous pouvez placer des signets dans un document predefini (ou un modele de docu- 
ment) pour reperer les endroits que la macro doit remplir. Evidemment, la macro 
doit connaitre le nom de chaque signet et le type d'information a y inserer. 

Lexemple suivant initialise le curseur d'ecriture a l'emplacement repere par un signet, 
puis ecrit un texte. Le document du Zip telechargeable contient un signet dans le texte 
principal, un autre dans un tableau, un troisieme designant une zone dans l'en-tete. 

rem Code08-10.odt bibli : Ecri reSurSi gnet Modulel 
Option Explicit 
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Sub InsererAuSignetO 

Dim monDocument As Object, leTexte As Object 
Dim unSignet As Object, monCurseur As Object 
monDocument = Thi sComponent 
' signet dans le texte principal 

unSignet = monDocument. Bookmarks. getByName("reperel") 
leTexte = unSignet. Anchor. Text 

monCurseur = leTexte . c reateTextCur so rByRange (unSignet .Anchor .Start) 
monCurseur. CharPosture = com. sun . star . awt . FontSl ant . ITALIC 
leTexte. insertString( monCurseur, "la ville de ", false) 
' signet dans une cellule d'un tableau Writer 
unSignet = monDocument . Bookmarks . getByName("repere2") 
leTexte = unSignet. Anchor. Text 

monCurseur = leTexte . c reateTextCur so rByRange (unSi gnet .Anchor . Start) 
leTexte. insertString( monCurseur, " derriere", false) 
unSignet = monDocument. Bookmarks. getByName("repere3") 
print "Repere3 = " & unSignet. Anchor .String 
End Sub 

Nous recuperons d'abord le signet parmi la collection des signets du document. 
Ensuite, la propriete Text nous fournit le support de texte dans lequel le signet est 
insere. La propriete Anchor (ancre) du signet est une zone de texte a partir de laquelle 
nous creons un curseur d'ecriture. Linteret de cette methode est de fonctionner quel 
que soit le support texte dans lequel se trouve le signet, par exemple dans un tableau 
ou dans un bas de page. Nous recuperons le texte repere par le troisieme signet grace 
a la propriete Stri ng de l'objet Anchor. 

Apres avoir essaye l'exemple sur un document, si vous annulez les modifications de 
texte, vous constaterez que les signets disparaitront aussi ! 

Le nom du signet doit etre ecrit exactement comme dans sa definition. Linstruction 
getByName declenchera une exception s'il n'existe aucun signet de ce nom. Vous 
pouvez tester l'existence du signet ainsi : 

if monDocument . Bookmarks . hasByName("ecri re_i ci ") then 

rem le signet existe 
end if 

L'objet Anchor peut fournir l'objet dans lequel se trouve le signet, par exemple une 
cellule de tableau ou un cadre, voir tableau 8-55. 



Tableau 8-55 Sites possibles d'implantation d'un signet 




Type 





Cell 



Object 



Une cellule d'un tableau. 



TextFrame 



Object 



Un cadre. 
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Tableau 8-55 Sites possibles d'implantation d'un signet (suite) 

I'impli 



TextTabl e 


Object 


Le tableau auquel appartient la cellule. 


TextSection 


Object 


Une section de texte. 


TextFi eld 


Object 


Un champ. 


FootNote 


Object 


Une note de bas de page. 


EndNote 


Object 


Une note de fin de document. 



Ces differents objets peuvent etre non significatifs pour un signet particulier. On 
verifie facilement 1' existence d'un objet avec la fonction Basic IsEmpty : 

maCellule = unSi gnet .Anchor . Cell 
if IsEmpty(maCellule) then 

print "Le signet n'est pas dans une cellule" 
el se 

' le signet est bien dans une cellule 
end if 

Un signet peut s'averer utile pour renvoyer contextuellement par macro vers la page 
le contenant. S'agissant d'affichage, nous allons tout naturellement nous tourner vers 
la notion de curseur visible vue precedemment. 



rem Code08-10.odt 
Option Explicit 



bibli : Ecri reSurSi gnet Module4 



Sub RenvoyerAuSignetO 

Dim monDocument As Object, curseurVisible As Object 
Dim unSignet As Object, laCible As Object 
monDocument = Thi sComponent 

unSignet = monDocument. Bookmarks .getByName("repere3") 
laCible = unSignet .Anchor 

curseurVisible = monDocument. CurrentController.ViewCursor 
curseurVi si bl e . gotoRange (1 aCi bl e , f al se) 
End Sub 

A partir du nom du signet, nous pouvons utiliser la methode getByName de la collec- 
tion Bookmarks du document pour recuperer le signet en question. 

L'objet ViewCursor a une methode gotoRange prenant un TextRange comme argu- 
ment. Nous creons done la variable 1 aCi bl e contenant l'objet Anchor de notre signet. 
Cette variable 1 aCi bl e est un TextRange. 

II ne nous reste plus alors qua obtenir le curseur visible et appeler sa methode 
gotoRange. 



Les documents Writer 

Chapitre 8 

Inserer un signet 

L'exemple suivant insere un signet dans le texte principal. 

rem Code08-10 . odt bibli : Ecri reSurSi gnet Module2 
Option Explicit 

Sub AjouterUnSignetO 

Dim monDocument As Object, monTexte As Object 
Dim monSignet As Object, monCurseur As Object 
monDocument = Thi sComponent 

monSignet = monDocument . createlnstanceC'com . sun . star . text . Bookmark") 

monSignet . Name = "Signet ajoute" 

monTexte = monDocument .Text 

monCurseur = monTexte. createTextCursor 

monCu rseu r . gotoNextParag raph (Fal se) 

monCurseur . gotoNextSentence(Fal se) 

monTexte. insertTextContent(monCurseur, monSignet, false) 

End Sub 



Trouver les signets 

L'objet Bookmarks nous permet de connaitre tous les signets du document. Le 
nombre de signets est fourni par la propriete Count, leurs noms sont obtenus avec la 
propriete Name de chaque objet signet. On obtient un signet d'un nom particulier 
avec la fonction getByName de l'objet collection. On peut aussi acceder a un signet par 
son numero d'ordre avec la methode getBylndex. Avec OOoBasic, le getBylndex 
peut etre omis, comme si on indexait une variable tableau. 

rem Code08-10 . odt bibli : Ecri reSurSi gnet Module3 
Option Explicit 

Sub Li sterSignetsO 

Dim monDocument As Object, leTexte As Object 
Dim unSignet As Object, lesSignets As Object 
Dim x As Long 

monDocument = Thi sComponent 
lesSignets = monDocument . Bookmarks 
for x = 0 to lesSignets. Count -1 

unSignet= 1 esSi gnets (x) 

print "Signet : " & unSignet. Name 
next 
End Sub 

Attention, l'ordre des signets dans la liste de Bookmarks ne correspond pas systemati- 
quement a l'ordre dans le document. 
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Liens hypertextes 

Les gros documents ou les documents scientifiques peuvent tirer avantage de facilites 
de navigation procures par les liens hypertextes. Ces liens peuvent etre de plusieurs 
natures : interne au document, en direction d'un autre document ou meme directe- 
ment sur Internet. 

Bien que plusieurs methodes soient possibles, nous presentons celle que nous consi- 
derons la plus simple. 

monCurseur = thisComponent.Text.createTextCursor 
monCurseur.HyperlinkURL = "#Tabl eaul | tabl e" 
moncurseur . Stri ng = "Essai" 

Cette methode est basee sur un TextCursor dont il suffit de definir la propriete 
HyperlinkURL. Avec ce qui a ete vu auparavant, une plage quelconque de caracteres 
peut etre ainsi definie comme lien hypertexte. 

Maintenant, nous avons trois possibilites de liens : 

• lien interne au document ; 

• lien vers un autre document ; 

• lien externe (URL). 

La difference ne va se faire que sur le contenu de la propriete Hyperl i nkURL. 

Lien externe 

Si vous avez defini un navigateur par defaut dans le parametrage d'OpenOffice.org 
(Outils>Options>OpenOffice.org>Programmes auxiliaires), vous pouvez definir un lien 
hypertexte pointant vers Internet dans votre document. II suffit de definir par exemple : 

monCurseur.HyperlinkURL = "http://www.google.fr" 

Cette URL peut egalement contenir des arguments pour les soumettre a un script sur 
un serveur. 

Lien vers un autre document 

Pour que le lien pointe sur un autre document, il suffit d'indiquer le chemin de ce 
document sous forme d'URL : 

monCurseur.HyperlinkURL = ConvertToURL("C:\Fichier.odt") 
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Lien interne au document 

II est possible de positionner l'arrivee du lien sur un element du document, en 
employant son nom. OpenOffice.org permet de nommer les objets inclus dans les 
documents. Le Navigateur accessible par la touche F5 permet de connaitre tous les 
elements du document classes par type. 

Cette notion de type est importante. Deux objets de nature differente pouvant porter 
le meme nom, le lien devra contenir cette information. 

En faisant une insertion manuelle de lien hypertexte interne, nous constatons, pour 
un tableau par exemple, que la syntaxe est la suivante : 

| monCurseur.HyperlinkURL = "#Tabl eaul | tab! e" 

Nous en deduisons done la regie suivante pour construire les liens internes : 
| monCurseur.HyperlinkURL = "#" & NomObjet & "|" & TypeObjet 

La chaine de caracteres representee par TypeObjet peut etre retrouvee lors d'une 
insertion manuelle. Le tableau 8-56 en donne les principales. 

Tableau 8-56 Types d'objets des liens hypertextes 



Tableau 


Le nom du tableau 


table 




Image 


Le nom de I'image 


graphic 




Cadre 


Le nom du cadre 


frame 




Section 


Le nom de la section 


regi on 




Signet 


Le nom du signet 




Pas d'extension TypeObjet, meme si le signet 
se trouve dans un tableau, dans un cadre, etc. 


Titre 


La chame de caracte- 
res du titre 


outl i ne 




Objet OLE 


Le nom de I'objet 


ole 


L'objet a ete insere par exemple avec le menu 
lnsertion>Objet 



Lien vers un endroit dans un autre document 

En combinant les deux methodes precedentes, il est possible de construire un lien 
hypertexte sur un fichier externe a un endroit specifique : 

monURL = ConvertToURL("C:\Fichier.odt") 
monCurseur.HyperlinkURL = monURL & "#tableaul | table" 
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Les formes et les images 

Nous expliquerons ici les particularities de Writer concernant les figures de dessin ou 
formes et les images. Dans le chapitre consacre a Draw nous decrivons en detail les 
differents types de formes, leurs proprietes, leur manipulation, ainsi que les pro- 
prietes des images. Vous y trouverez aussi des explications sur d'autres types d'objets 
inseres dans une page de dessin, qui s'appliquent egalement a la page de dessin d'un 
document Writer. 



La page de dessin 



Les formes d'un document Writer sont placees sur une unique page de dessin (en anglais 
draw page), qui s'etend sur le document tout entier. L'objet page est accessible ainsi : 

Dim maPage As Object 

maPage = monDocument .DrawPage 

Cette page de dessin dans Writer ne comporte pas les proprietes d'une page Draw, 
mais uniquement la liste des objets sur cette page. Une page de dessin dans Writer 
comporte 6 couches, non documentees, qui ne sont pas accessibles directement par 
l'API. Elles sont enumerees au tableau 8-57. Une forme, ainsi qu'une image, com- 
porte 3 proprietes : 

• Layerld, le numero de couche ou se trouve la forme ou l'image ; 

• LayerName, le nom de la couche ou se trouve la forme ou l'image ; 

• Opaque, qui fait passer la forme ou l'image au premier plan ou en arriere-plan, 
selon qu'on lui attribue respectivement la valeur True ou False. Cette modifica- 
tion correspond a la deplacer sur une autre couche. 

Apres son insertion dans la page, la forme ou l'image se trouve en arriere-plan. Pour 
la selectionner facilement, on doit la passer en avant-plan. 

Tableau 8-57 Couches de la page de dessin 



0 


Hell 


Couche visible, en arriere-plan. 


1 


Heaven 


Couche visible, au premier plan. 


2 


Controls 


Couche visible, utilisee par les controles de formulaire. 


3 


Invi si bl eHel 1 


Couche invisible, usage inconnu. 


4 


Invi si bl eHeaven 


Couche invisible, usage inconnu. 


5 


Invi si bl eControl s 


Couche invisible, usage inconnu. 
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Les formes 

Apres avoir cree un objet forme, son insertion sur la page de dessin se fait 
facilement : 

maPage .add(maForme) 

Malheureusement, le positionnement est alors obligatoirement ancre a la page de 
dessin. Ceci pose probleme avec un document de plusieurs pages de texte, aussi 
emploierons-nous une autre methode. 

Inserer une forme a la position du curseur 

La meilleure solution pour inserer une forme est d'utiliser un curseur d'ecriture et la 
methode i nsertTextContent de l'objet texte. Nous allons voir comment inserer une 
ellipse. Le principe ressemble pour partie a l'insertion d'un cadre dans un document 
Writer, et pour partie a l'insertion d'une forme dans Draw. 

rem Code08-09.odt bibli : Dessins Modulel 
Option Explicit 

Sub AjouterEllipseO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object, maForme As Object 
Dim dimensionsForme As New com. sun. star. awt. Size 
Dim positionForme As New com. sun. star. awt. Point 
monDocument = Thi sComponent 
monTexte = monDocument .Text 
monCurseur = monTexte . createTextCursor 

monCurseur . gotoNextParagraph(Fal se) ' deplacer le curseur 

maForme = monDocument . createInstance("com . sun . star . drawi ng . Ell ipseShape") 
dimensionsForme. Width = 2600 ' 26 mm de large 
dimensionsForme. Height = 1200 ' 12 mm de haut 
positionForme.x = 3500 ' 35 mm a droite du point d'ancrage 
positionForme.y = 1300 ' 13 mm en dessous du point d'ancrage 

maForme. Size = dimensionsForme 

maFo rme . AnchorType = com . sun . star . text . TextContentAncho rType . AT_PARAGRAPH 
monTexte. i nsertTextContent (monCurseur, maForme, false) 
maForme. Position = positionForme 

maForme. Surround = com. sun. star. text. WrapTextMode. RIGHT 
maForme . Name = "Ovale" ' donner un nom a cette forme 
End Sub 
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Contrairement aux cadres, seul le positionnement absolu est possible pour les 
formes. Les distances sont exprimees en 1/100 de millimetres, mesurees du coin 
haut-gauche de l'ancre au coin haut-gauche de la forme. Les valeurs possibles 
d'ancrage sont celles listees pour ancrer un cadre. 

BOGUE Position et dimensions d'une forme 

Si vous changez par programme la position ou les dimensions d'une forme existante, le document ne 
passe pas a I'etat « modifie ». Vous pouvez cependant forcer cet etat (voir le chapitre 7). 

Concernant l'adaptation de la forme au texte (menu contextuel Adaptation du 
texte>Editer), on retrouve toutes les proprietes d'adaptation du texte deja vues a 
propos des cadres, auxquelles s'ajoutent : 

• ContourOutside, de type Boolean, qui correspond a la coche Seul I'exterieur dans 
l'interface utilisateur. Ceci sert a eviter que le texte n'apparaisse dans la partie con- 
cave d'une figure complexe. 

• SurroundContour, de type Boolean, qui correspond a la coche Contour de l'inter- 
face utilisateur. 

Inserer plusieurs formes 

A chaque insertion d'une forme, il est necessaire d'obtenir un nouvel objet forme, 
meme si on insere plusieurs fois le meme type de forme. II faut aussi reinitialiser a 
chaque fois les proprietes de la forme. Dans cet exemple, on insere deux rectangles 
identiques a la meme position, ancres a la page, Fun dans la page 4, l'autre dans la 
page 2 du document Writer. Nous leur donnons un nom, qui nous servira dans le 
prochain exemple. 

rem Code08-09.odt bibli : Dessins Module2 
Option Explicit 

Sub PlusieursFormesO 
I Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object, maForme As Object 
Dim dimensionsForme As New com. sun. star. awt. Size 
Dim positionForme As New com. sun. star. awt. Point 
monDocument = Thi sComponent 
monTexte = monDocument .Text 
monCurseur = monTexte. createTextCursor 

' pour un ancrage page la position du curseur est indifferente 

dimensionsForme. Width = 8400 ' 84 mm de large 
dimensionsForme. Height = 2530 ' 25,3 mm de haut 



Les documents Writer 

Chapitre 8 



positionForme.x = 3500 ' 35 mm a droite du point d'ancrage 
positionForme. y = 5300 ' 53 mm en dessous du point d'ancrage 
' premiere forme inseree sur la page 4 

maForme = monDocument . createInstance("com . sun . star . d rawi ng . Rectangl eShape") 
maForme . AnchorType = com . sun . star . text . TextContentAnchorType . AT_PAGE 
maForme. AnchorPageNo = 4 

monTexte.insertTextContent(monCurseur, maForme, false) 
maForme. Size = dimensionsForme 
maForme. Position = positionForme 

maForme. Name = "Recti" ' donner un nom a cette forme 
' deuxieme forme en page 2, position et dimensions identiques 
maForme = monDocument . createInstance("com . sun . star . d rawi ng . Rectangl eShape") 
I maForme. AnchorType = com. sun. star. text. TextContentAnchorType. AT_PAGE 
maForme. AnchorPageNo = 2 

monTexte.insertTextContent(monCurseur, maForme, false) 
maForme. Size = dimensionsForme 
maForme. Position = positionForme 

maForme. Name = "Rect2" ' donner un nom a cette forme 
End Sub 

Retrouver et supprimer une forme 

Le Navigateur de Writer est incapable de lister les objets dessins d'un document. Nean- 
moins, par macro, nous somme capables de retrouver une forme nommee sur la page de 
dessin. Nous emploierons a cet effet la routine utilitaire Fi ndObjectByName decrite a 
l'annexe B. Elle est recopiee dans la bibliotheque Standard du document exemple. 

rem Code08-09 . odt bibli : Dessins Module3 
Option Explicit 

Sub SelectionnerFormeO 

Dim monDocument As Object, maPage As Object, maForme As Object 

monDocument = thi sComponent 

maPage = monDocument . DrawPage 

maForme = Fi ndObjectByName (maPage, "Recti") 

if IsNull (maForme) then 

print "II n'existe aucune forme de ce nom" 
el se 

monDocument . Cur rentControl 1 er . Sel ect (maForme) 

end if 
End Sub 

Une fois la forme trouvee, nous pouvons la modifier. Ici, nous nous contentons de la 
selectionner de maniere visible en employant la methode select du controleur du 
document. 
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La suppression d'une forme s'effectue a partir de la page de dessin, par sa methode 
remove. 

maPage. remove(maForme) 

Interaction entre la forme et les autres objets 

Une forme inseree avec la methode i nsertTextContent de l'objet texte du document 
se place par defaut en arriere-plan par rapport a un cadre, un tableau, un en-tete ou 
un pied de page. La forme pourra cependant deplacer un element de tableau, en 
fonction de 1' adaptation au texte. 

Linsertion de forme par la methode i nsertTextContent de l'objet texte fonctionne 
aussi avec un objet texte provenant d'un cadre, d'un en-tete ou d'un pied de page. 
Cependant, la forme se trouve alors aussi en arriere-plan, masquee par l'objet auquel 
elle est ancree. 

On fait passer la forme au premier plan en affectant la valeur True a sa propriete 
Opaque, de type Bool ean. La valeur Fal se la renvoie a 1' arriere-plan. 

maForme .Opaque = true 1 passer la forme au premier plan 



Le fait d'ancrer une forme a un cadre, par exemple, ne la contraint pas a rester dans ce cadre. Elle peut en 
deborder ou se trouver en dehors. 



Les images 



Les principes d'insertion, de recuperation ou de suppression d'une image sont simi- 
laires a ce que nous avons vu pour les formes. 



Inserer une image a la position du curseur 

De meme que pour les formes, l'insertion d'image utilise un curseur d'ecriture et la 
methode i nsertTextContent de l'objet texte. 

rem Code08-09.odt bibli : leslmages Modulel 
Option Explicit 

Sub AjouterlmageO 

Dim monDocument As Object, monTexte As Object 
Dim monCurseur As Object, monlmage As Object 
Dim positionlmage As New com. sun. star. awt. Point 
monDocument = Thi sComponent 
monTexte = monDocument .Text 
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monCurseur = monTexte . createTextCursor 
monCurseur.gotoNextParagraph(False) ' deplacer le curseur 

positionlmage.x = 1500 ' 15 mm a droite du point d'ancrage 
positionlmage.y = 1300 ' 13 mm en dessous du point d'ancrage 

monImage=monDocument.createInstance("com. sun. star. drawi ng .GraphicObjectShape") 
monlmage.CraphicURL = ConvertToURL("C:\Docs 0pen0ffice\Logo0pen0ffice.png") 
monlmage . AnchorType = com . sun . star . text .TextContentAnchorType . AT_PARAGRAPH 
monTexte. insertTextContent (monCurseur, monlmage, false) 
resi zelmageByWidth (monlmage , 5500) ' largeur en 1/100 de mm 
monlmage. Position = positionlmage 

monlmage. Surround = com. sun. star. text. WrapTextMode. RIGHT 
monlmage. Name = "Logol" ' donner un nom a cette image 
End Sub 

Pour dimensionner l'image sur le document tout en conservant les proportions de 
l'image, nous utiliserons la routine utilitaire resi zelmageByWidth, que nous avons 
extraite de 1' annexe B de ce livre. Cette routine est recopiee dans la bibliotheque 
Standard du document exemple. 

Inserer plusieurs images 

A chaque insertion d'une image, il est necessaire d'obtenir un nouvel objet image, 
meme si on insere plusieurs fois la meme. II faut aussi reinitialiser a chaque fois les 
proprietes de la forme. Le document Codell-09.odt du Zip telechargeable contient 
un exemple. 

Retrouver, supprimer une image 

La methode et le codage exposes pour les formes s'appliquent aussi bien a une image 
qu'on a nommee. 



Actualiser le document 

LAPI n'offre pas une methode simple equivalente a la commande de menu 
Outils>Actualiser>Tout actualiser pour actualiser le document. S'il est visible, vous pouvez 
employer le Dispatcher (voir chapitre 14) pour executer la commande 
equivalente . Uno : UpdateAl 1 . Sinon, chaque element actualisable est un cas particulier. 

Pour reformater les pages du document et mettre a jour le nombre de pages : 
monDocument . reFormat 
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Pour reactualiser les liens (par exemples les images liees) : 
monDocument . updateLi nks 

Pour mettre a jour tous les index (table des matieres, index lexical, etc.), on doit recu- 
perer chaque objet index de la collection Documentlndexes : 

Dim leslndexes As Object, unlndex As Object, x As Long 

leslndexes = monDocument . Documentlndexes 
for x = 0 to 1 eslndexes . Count -1 
unlndex = leslndexes(x) 
unlndex. update 
next 

La mise a jour des champs de texte emploie la methode refresh, voyez par exemple 
la section « Inserer un champ utilisateur ». 



Les informations sur le document 

La propriete WordSeparator d'un document Writer est une chaine de caracteres dont 
chacun est reconnu comme separateur de mots. Par defaut, elle contient : parenthese 
ouvrante, fermante, espace, tabulation, Line-Feed, Form-Feed. Vous pouvez eventuel- 
lement modifier cette liste. 

Diverses statistiques sur le contenu du document Writer sont facilement a obtenir. 

rem Code08-08 . odt bibli : Standard Module2 
Option Explicit 

Sub affi cherStats 

Dim monDocument As Object, liste As String, cr As String 
monDocument = Thi sComponent 
cr = chr(13) 

With monDocument 



liste = 


"Nombre de pages = 


' & 


. CurrentController . PageCount & 


cr & 


"Nombre 


de 


lignes = " 


& 


.CurrentController.LineCount & 


cr & 


"Nombre 


de 


paragraphes = " 


& 


. ParagraphCount & cr & 




"Nombre 


de 


mots = " 


& 


.WordCount & cr & 




"Nombre 


de 


caracteres = " 


& 


.CharacterCount & cr & 




"Nombre 


de 


tableaux = " 


& 


.TextTables. Count & cr & 




"Nombre 


de 


cadres = " 


& 


.TextFrames. Count & cr & 




"Nombre 


de 


signets = " 


& 


. BookMarks. Count & cr & 
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"Nombre de sections = " & . TextSections. Count & cr & _ 

"Nombre d'images = " & .GraphicObjects. Count 

End With 

MsgBox(liste, 0, "Stati sti ques du document Writer") 
End Sub 

L'instruction Wi th evite de repeter monDocument a chaque ligne. Le nombre de pages et 
de lignes dependant de la mise en forme, l'API reformate automatiquement le docu- 
ment quand on accede a ces deux proprietes, ce qui peut prendre un certain temps. 



Configuration d'affichage du document 

Ces proprietes du document Writer (voir le tableau 8-58), qui existent dans l'inter- 
face utilisateur principalement au niveau Outils>Options>OpenOffice.org Writer, sec- 
tions Affichage et Aide au Formatage, sont accessibles a partir de l'objet controleur du 
document. Elles ne sont pas memorisees a la sauvegarde du document. 

rem Code08-08 . odt bibli : Standard Modulel 
Option Explicit 

Sub ConfigDocWriterO 

Dim monDocument As Object, confVisu As Object 
monDocument = thi sComponent 

confVisu = monDocument. Cur rentController .View/Settings 

With confVisu 

. ShowVertRul er = MsgBox("ShowVertRul er ?", 4) = 6 

. IsVertRulerRightAligned = MsgBox("IsVertRul erRi ghtAl i gned ?", 4) = 6 
. ShowOnl ineLayout = MsgBox("ShowOnl i neLayout ?", 4) = 6 

end With 

End Sub 



Tableau 8-58 Proprietes d'affichage pour Writer 



Propriete Type Signification 


ShowAnnotati ons 


Bool ean 


True pour afficher I'indicateur de note. 


ShowNonpri nti ngCharacters 


Boolean 


True pour afficher les caracteres speciaux selon la valeur 
des indicateurs ShowSpaces, ShowBreaks, etc. 


ShowBreaks 


Boolean 


True pour afficher les retours de ligne. 


ShowParaBreaks 


Bool ean 


True pour afficher les fins de paragraphe. 


ShowFootnoteBackg round 


Boolean 


True pour afficher un fond gris sur les symboles de note 
de bas de page. 


ShowIndexMarkBackg round 


Boolean 


True pour afficher un fond gris sur les marques d'index. 
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Tableau 8-58 Proprietes d'affichage pour Writer (suite) 



Propriete 


Type 


Signification 


ShowProtectedSpaces 


Bool ean 


True pour afficher un fond gris sur les espaces insecables. 


ShowSoftHyphens 


Boolean 


True pour afficher un fond gris sur les tirets conditionnels. 


Show/Spaces 


Boolean 


True pour afficher un point pour chaque espace. 


ShowTabstops 


Boolean 


True pour afficher les tabulations. 


ShowTextFi el dBackground 


Boolean 


True pour afficher un fond gris sur les champs. 


ShowFi el dCommands 


Bool ean 


True pour afficher les noms des champs. 


ShowHidden Paragraphs 


Boolean 


True pour afficher les paragraphes masques. 


ShowHiddenText 


Bool ean 


True pour afficher le texte cache. 


ShowHiddenCharacters 


Boolean 


True pour afficher les caracteres caches. 


ShowRul ers 


Boolean 


True pour autoriser I'affichage des regies, selon les 
valeurs de ShowHori Rul er et ShowVertRul er. 


ShowHori Rul er 


Boolean 


True pour afficher la regie horizontale. 


ShowVertRul er 


Boolean 


True pour afficher la regie verticale. 


ShowTextBoundaries 


Boolean 


True pour afficher les limites de texte dans la page. 


ShowTabl eBoundari es 


Boolean 


True pour afficher les limites des tableaux. 


ShowTabl es 


Bool ean 


True pour afficher les tableaux. 


ShowHori Scrol 1 Bar 


Boolean 


True pour afficher I'ascenseur horizontal. 


ShowVertScrol 1 Bar 


Boolean 


True pour afficher I'ascenseur vertical. 


IsRasterVisible 


Boolean 


True pour afficher la grille. 


IsSnapToRaster 


Boolean 


True pour aimanter la grille. 


RasterResol utionX 


Long 


Espacement horizontal de la grille, en 1/100 de mm. 


RasterResol utionY 


Long 


Espacement vertical de la grille, en 1/100 de mm. 


IsVertRul erRightAl i gned 


Bool ean 


True pour afficher les positions de la regie verticale et de 
I'ascenseur vertical. 


SmoothScrol 1 i ng 


Bool ean 


True pour un defilement doux. 


SolidMarkHandles 


Bool ean 


True pour afficher des grandes poignees de deplacement. 


Show/Graphics 


Bool ean 


True pour afficher les images. 


ShowDrawi ngs 


Boolean 


True pour afficher les formes. 


ShowFi el dCommands 


Boolean 


True pour afficher le contenu des champs. 


ShowOnl i neLayout 


Boolean 


True pour afficher comme un document HTML. 


ZoomType 


Integer 


Facteur de zoom ; constante nommee (voir le chapitre 7). 


ZoomVal ue 


Integer 


Facteur du zoom en pourcentage (voir le chapitre 7). 
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Options d'impression 



Le service com. sun. star. text. DocumentSettings invoque depuis le document 
Writer permet de lire et modifier les options d'impression visibles dans l'interface 
utilisateur. Elles sont listees au tableau 8-59. La plupart sont de type Bool ean, la 
valeur True correspondant a la case cochee. 

Dim sv As Object 

sv = monDocument . createln stance ("com. sun . star . text . DocumentSetti ngs") 
sv. PrintGraphics = False 

sv . Pri ntAnnotati onMode = com . sun . star . text . NotePri ntMode . PACE_END 

Pour l'impression effective, reportez-vous au chapitre 7. 

Tableau 8-59 Proprietes relatives a l'impression 



Pri ntReversed 


Boolean 


Pages>Ordre inverse 


Pri ntEmptyPages 


Boolean 


Autres>lmprimer automatiquement les pages blan- 
ches inserees 


Pri ntPaperFromSetup 


Boolean 


Autres>D'apres les parametres de rimprimante 


Pri ntLeftPages 


Boolean 


Pages>Pages de gauche 


Pri ntRi ghtPages 


Boolean 


Pages>Pages de droite 


Pri ntTabl es 


Boolean 


Contenu>Tableaux 


Pri ntControl s 


Bool ean 


Contenu>Champs de controle 


Pri ntProspect 


Boolean 


Page>Brochure 


PrintGraphics 


Boolean 


Contenu>lmages 


Pri ntPageBackground 


Boolean 


Contenu>Arriere-Plan 


Pri ntDrawi ngs 


Boolean 


Contenu>Dessins 


PrintBlackFonts 


Bool ean 


Contenu>lmprimer en noir 


Pri ntAnnotati onMode 


Integer 


Notes>choix ; constantes nommees (voir le tableau 8-60) 



La propiete Pri ntAnnotati onMode recoit une constante nommee de la forme 
com . sun . star . text . NotePri ntMode . D0C_END 

Tableau 8-60 Constantes d'impression de notes 





NOT 


Notes>Aucun(e) 


ONLY 


Notes>Notes uniquement 
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Tableau 8-60 Constantes compression de notes (suite) 



Constante 


Equivalence interface utilisateur 


DOC_END 


Notes>Fin du document 


PAGE_END 


Notes>Fin de la page 



Conclusion 

Nous venons de parcourir les differents concepts accessibles par l'API concernant les 
documents Writer. Notre approche etant orientee vers la redaction, nous y avons 
expose les notions de curseur et de style. 

Le chapitre suivant traitera de l'API pour manipuler un document Calc. 



9 

Les documents Calc 



Ce chapitre montre comment acceder aux objets elementaires de Calc que sont les 
feuilles et les cellules ; il decrit leurs proprieties et explique comment les manipuler. 
Nous verrons egalement des methodes qui repondent aux besoins les plus courants : 
activer le calcul des formules, lire et ecrire les donnees d'un tableau, invoquer une 
fonction de Calc, inserer un lien hypertexte, etc. D'autres manipulations plus specia- 
lisees, notamment sur les styles, les zones nominees, les en-tetes, pieds de page et 
diagrammes, sont aussi presentees avec des exemples. Enfin, l'impression d'un docu- 
ment Calc presente quelques particularites que nous decrirons. 

API Reference sur Calc (en anglais) 

La documentation de I'API est decrite dans le Developer's Guide, chapitre Spreadsheet Documents. 
► http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ 
OpenOffice.org_Developers_Guide 



Lecture et manipulation de feuilles 

Les limites d'un document Calc 

Les limites d'un document Calc ont evolue au fil des versions d'OpenOffice.org. 
• Un document comporte jusqu'a 256 feuilles. 
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• Une feuille contient jusqu'a 1024 colonnes depuis la version 3.0. Auparavant la 
limite etait de 256. 

• Une feuille contient jusqu'a 65536 lignes depuis la version 3.0. Auparavant la 
limite etait de 32 000. 

Une simple multiplication montre qu'il s'agit de limites d'adressage : si toutes les cel- 
lules etaient occupees, il n'y aurait jamais assez de memoire pour charger le document. 

Proteger le document Calc 

II s'agit de la commande de menu Outils>Protection>Document. Un document Calc 
protege interdit d'aj outer, supprimer ou changer l'ordre des feuilles, tout en permet- 
tant de modifier leur contenu. 

Un document Calc dispose de trois methodes pour gerer cette protection : 

• i s Protected est une fonction booleenne qui renvoie True si le document est pro- 
tege par un mot de passe. 

• protect applique le mot de passe donne en argument (une chaine de caracteres). 

• unprotect supprime le mot de passe, a condition qu'il soit donne en argument. 

Vous remarquerez qu'il n'existe pas de methode permettant de lire le mot de passe. 
Pour l'exemple, nous appliquerons seulement un mot de passe statique. En pratique, 
le mot de passe doit etre fourni par l'utilisateur. 

rem Code09-01.ods bibli : Protection Modulel 
Option Explicit 

Sub ProtegerDocumentCal c() 

Dim monDocument As Object, lesFeuilles As Object 
Dim maFeuille As Object, motPasse As String 
monDocument = Thi sComponent 

if monDocument . isProtected then 

motPasse = InputBox("Le document est deja protege." & 
chr(13) & "Mot de passe ?") 

monDocument. unprotect(motPasse) ' enlever le mot de passe 
elseif MsgBox("Proteger le document ?", 260) = 6 then 

monDocument. protect("0pen0ff ice") ' mettre un mot de passe 
end if 
End Sub 



Acceder aux feuilles existantes 

Le document Calc nous expose l'objet Sheets (anglais pour feuilles) qui est la collec- 
tion des feuilles du document. Le nombre actuel de feuilles est expose par la pro- 
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priete Count de l'objet Sheets. On peut acceder a une feuille par son numero d'ordre 
avec la methode getBylndex. Avec OOoBasic, le getBylndex peut etre omis, comme 
si on indexait une variable tableau. La numerotation part de zero, correspondant a la 
feuille dont l'onglet est le plus a gauche dans la fenetre Calc. Le nom d'une feuille 
nous est indique dans sa propriete Name. 

Nous en savons suffisamment pour enumerer les feuilles d'un document Calc : 

rem Code09-01 . ods bibli : Feuilles Modulel 
Option Explicit 

Sub EnumererFeuillesO 

Dim monDocument As Object, lesFeuilles As Object, uneFeuille As Object 

Dim x As Long, nbF As Long 

monDocument = Thi sComponent 
lesFeuilles = monDocument. Sheets 
nbF = lesFeuilles. Count 

MsgBox("Nombre de feuilles : " & nbF) 
for x = 0 to nbF -1 

uneFeuille = lesFeuilles(x) 

MsgBox("Feuille de rang : " & x & chr(13) & _ 
"Nom : " & uneFeuille. Name) 

next 
End Sub 

Nous pouvons done acceder aux feuilles d'un classeur avec les index 0, 1,2, etc. 
Cependant, comme l'utilisateur peut changer l'ordre des feuilles, vous ne devez sup- 
poser aucune correspondance entre index et identite de feuille. Attention aussi aux 
feuilles ayant conserve leur nom par defaut : le nom propose par OpenOffice depend 
de la langue de l'interface utilisateur lors de la creation de la feuille, par exemple en 
francais Feuille2 ; en anglais, Sheet2 ; en espagnol, Hoja2. Le seul moyen sur 
d'obtenir l'objet feuille que Ton souhaite consiste a nommer la feuille puis utiliser son 
nom. L'objet Sheets nous fournit pour cela la methode getByName, qui prend en 
argument le nom de la feuille souhaitee et renvoie l'objet correspondant, s'il existe. 
S'il n' existe pas, une erreur se produira ; aussi l'objet Sheets nous donne-t-il le 
moyen de tester 1' existence d'une feuille d'un nom donne avec la fonction hasByName, 
qui renvoie True dans le cas positif. 

Nous allons utiliser ces notions pour renommer une feuille. Pour cela, il suffit de 
modifier la propriete Name de la feuille. Apres quoi, nous executerons la macro prece- 
dente pour lister les differentes feuilles. 
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rem Code09-01.ods bibli : Feuilles Module2 
Option Explicit 

Sub RenommerFeuilleO 

Dim monDocument As Object, lesFeuilles As Object, uneFeuille As Object 
Dim noml As String, nom2 As String 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 

noml = InputBox("Nom actuel de la feuille") 
if lesFeuilles.hasByName(noml) then 

nom2 = InputBox("Nouveau nom pour la feuille") 

' recuperer la feuille "noml" 

uneFeuille = lesFeuilles. getByName(noml) 

uneFeuille. Name = nom2 ' renommer cette feuille 

EnumererFeui 11 es ' lister les feuilles du document 
el se 

MsgBox(noml & " n'existe pas", 16) 
end if 
End Sub 

Executez la macro, vous verrez l'onglet de la feuille concernee changer de nom. 
Attention a la casse ! Les noms de feuilles doivent etre ecrits en respectant les majus- 
cules et minuscules. 



Ajouter une nouvelle feuille 

La methode insertNewByName de l'objet Sheets sert a creer une nouvelle feuille 
vierge. 

• Le premier argument est le nom de la nouvelle feuille. 

• Le deuxieme est la position que celle-ci occupera dans le classeur, decalant les 
feuilles existantes a partir de cette position. 

Si la position a pour valeur zero, la feuille sera inseree en tete. Si la valeur de position 
est superieure ou egale au nombre de feuilles actuel, la feuille sera ajoutee a la fin. 

II n'est pas vraiment pratique d'inserer une feuille a une position, car l'utilisateur peut 
modifier la structure du document. II est plus sur de se positionner par rapport a une 
feuille dont on connait le nom. Comment recuperer la position de cette feuille ? 
Anticipant sur la section « Obtenir les coordonnees d'une zone de cellules », nous 
utilisons la propriete RangeAddress de la feuille. Elle fournit une structure dontl'ele- 
ment Sheet est precisement la position de la feuille. 
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rem Code09-01 . ods bibli : Feuilles Module3 
Option Explicit 

Sub AjouterFeuilleO 

Dim monDocument As Object, lesFeuilles As Object 

Dim Fl As Object, indexFl As Long 

Dim noml As String, nom2 As String 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

noml = InputBox("Inserer apres la feuille :") 

if 1 esFeui 11 es . hasByName(noml) then 

nom2 = InputBox("La nouvelle feuille aura pour nom :") 

Fl = 1 esFeui 11 es . getByName(noml) 

indexFl = Fl.RangeAddress. Sheet 

1 inserer apres la feuille "noml" 

lesFeuilles.insertNewByName(nom2, indexFl +1) 
el se 

MsgBox(noml & " n'existe pas", 16) 
end if 
End Sub 



Supprimer une feuille 

La methode removeByName de l'objet Sheets permet de supprimer une feuille a partir 
de son nom. Cet exemple demande un nom de feuille a supprimer ; si la chaine de 
caracteres est nulle, c'est que la demande est annulee ; dans le cas contraire, nous 
verifions qu'une feuille de ce nom existe avant de la supprimer. 

rem Code09-01 . ods bibli : Feuilles Module4 
Option Explicit 

Sub SupprimerFeuilleO 

Dim monDocument As Object, lesFeuilles As Object 
Dim noml As String 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 

Do 

noml = InputBox("Feuille a supprimer ?") 

if noml = "" then Exit Sub ' annulation, ne rien supprimer 

1 reposer la question en cas d'erreur 
Loop Until lesFeuilles. hasByName(noml) 
lesFeuilles. removeByName(noml) ' supprimer la feuille 
End Sub 
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Dupliquer une feuille 

Si votre classeur comporte une feuille parfaitement formatee et remplie, il est avanta- 
geux de creer une feuille en faisant une copie de la premiere. C'est l'objet de la 
methode copyByName de l'objet Sheets, qui comporte trois arguments, 
successivement : 

• le nom de la feuille servant de modele ; 

• le nom de la nouvelle feuille ; 

• la position que celle-ci occupera dans le classeur, decalant les feuilles existantes a 
partir de cette position. 

Dans cet exemple, nous ajoutons la feuille Fevrier apres la feuille Janvier, en 
copiant celle-ci. Pour la placer a la bonne position, nous utilisons le meme principe 
que pour aj outer une feuille. 

rem Code09-01.ods bibli : Feuilles Module5 
Option Explicit 

Sub DupliquerFeuilleO 

Dim monDocument As Object, lesFeuilles As Object 

Dim Fl As Object, indexFl As Long 

Dim noml As String, nom2 As String 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

noml = "Janvier" 

nom2 = "Fevrier" 

Fl = 1 esFeui 1 1 es . getByName(noml) 
indexFl = Fl.RangeAddress. Sheet 

' creer la feuille Fevrier a 1 'image de Janvier 
lesFeuilles.copyByName(noml, nom2 , indexFl +1) 
End Sub 



Deplacer une feuille dans le classeur 

La methode moveByName de l'objet Sheets permet de deplacer une feuille a une autre 
position dans la serie de feuilles du classeur. Elle prend comme arguments le nom de 
la feuille a deplacer et la nouvelle position. L'ennui, c'est que cette position est mal 
calculee. Faites quelques essais avec cet exemple. 

rem Code09-01.ods bibli : Feuilles Module6 
Option Explicit 

Sub DeplacerFeuilleO 

Dim monDocument As Object, lesFeuilles As Object 
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Dim uneFeuille As Object, rep As String, nouvPos As Long 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
Do 

rep = InputBox("Nouvelle position de la feuille Ecrire ?") 
if Len(rep) = 0 then Exit Do 
nouvPos = rep 

1 esFeui 1 les .moveByName("Ecri re" , nouvPos) 
Loop 
End Sub 

Si la nouvelle position conduit a deplacer l'onglet de la feuille vers la gauche, c'est 
correct : la position correspond a la nouvelle valeur de l'index pour la feuille 
(n'oubliez pas que l'index commence a zero). En revanche, si la nouvelle position 
conduit a deplacer l'onglet vers la droite, il faut ajouter 1 a la valeur souhaitee pour 
l'index final... 



La feuille visible par l'utilisateur 

La feuille visible dans l'interface utilisateur est appelee en anglais active sheet (feuille 
active). Nous pouvons la recuperer avec la propriete ActiveSheet de l'objet contro- 
leur associe au document. Pour rendre visible une autre feuille, il suffit de l'affecter a 
la propriete ActiveSheet. 

rem Code09-01 . ods bibli : Feuilles Module7 
Option Explicit 

Sub FeuilleVisibleO 

Dim monDocument As Object, lesFeuilles As Object 

Dim uneFeuille As Object 

Dim textel As String, nom2 As String 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

uneFeuille = monDocument. CurrentController .ActiveSheet 

textel = "Feuille active : " & uneFeui 11 e . Name & chr(13) 

nom2 = InputBox(textel & "Quelle feuille rendre active ?") 

if 1 esFeui 11 es . hasByName(nom2) then 

uneFeuille = 1 esFeui 1 1 es . getByName(nom2) 

monDocument. CurrentController .ActiveSheet = uneFeuille 

end if 

End Sub 
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L'interface utilisateur permet de masquer une feuille d'un document Calc avec le 
menu Format>Feuille>Masquer. Par programmation, nous utiliserons la propriete 
IsVi si bl e de la feuille : 

maFeui lie. IsVi si ble = False 
Donnez la valeur True a la propriete IsVi si bl e pour demasquer la feuille. 

Proteger une feuille 

La protection d'une feuille consiste seulement a lui affecter un mot de passe. Le 
niveau de protection est defini au niveau des cellules, nous le verrons dans la section 
correspondante. 

Un objet feuille dispose lui aussi des trois methodes que nous avons deja vues pour la 
protection d'un document Calc: i sProtected, protect, unprotect. La methode 
employee est identique. 

rem Code09-01.ods bibli : Protection Module2 
Option Explicit 

Sub ProtegerFeuilleC) 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, motPasse As String 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Contenus") 

if maFeui 1 1 e . isProtected then 

motPasse = InputBox("La feuille est deja protegee." & _ 
chr(13) & "Mot de passe ?") 

maFeui 11 e.unprotect(motPasse) ' enlever le mot de passe 
elseif MsgBox("Proteger la feuille ?", 260) = 6 then 

maFeui 11 e . protect("OpenOff ice") 1 mettre un mot de passe 
end if 
End Sub 



Cellules et zones de cellules 



Une feuille de tableau se compose de cellules, auxquelles nous pouvons acceder indi- 
viduellement. Pour certains usages, on definit une zone de cellules, representant un 
rectangle compose de cellules. 
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Notez qu'une feuille est aussi une zone de cellules, couvrant toute la feuille. On 
retrouve done dans les proprietes d'une feuille celles d'une zone. 

Obtenir une cellule 

L'objet feuille fournit trois methodes pour faire reference a une cellule et y acceder : 

• en utilisant les coordonnees alphanumeriques habituelles d'une cellule ; 

• en utilisant le nom d'une zone reduite a cette cellule (menu 
lnsertion>Noms>Definir...) ; 

• en utilisant des coordonnees X, Y pour lesquelles X est le rang de la colonne et 
Y est le rang de la ligne, tous deux numerates a partir de zero. 

Dans l'exemple qui suit, nous recuperons de trois manieres differentes la cellule de 
coordonnees C2 dans la feuille nommee Janvier. Nous avons defini auparavant dans 
la feuille le nom de zone CelluleC2. La propriete Value de l'objet cellule renvoie la 
valeur numerique du contenu d'une cellule ; nous l'utilisons pour montrer que nous 
avons bien recupere la bonne cellule. 

rem Code09-01 . ods bibli : ZonesCellules Modulel 
Option Explicit 

Sub TrouverCelluleO 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maCellule As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 11 es . getByName(" Janvi er") 

' trois manieres d' obtenir la cellule de coordonnees C2 

maCellule = maFeuille. getCellRangeByName("C2") 

print "Acces al phanumeri que = " & maCellule. value 

maCellule = maFeuille.getCellRangeByName("CelluleC2") 

print "Acces par le nom = " & maCel 1 ul e . val ue 

' coordonnees X,Y : colonne C => X = 2 ligne 2 => Y = 1 

maCellule = maFeuille. getCellByPosition(2,l) 

print "Acces par la position XY = " & maCellule. value 

End Sub 

La zone nommee doit concerner la meme feuille que maFeui 1 1 e dans l'exemple. 

Attention a la casse ! Les noms de zone doivent etre ecrits en respectant les majus- 
cules et minuscules. 
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Obtenir une zone de cellules 

On recupere un objet zone de cellules de maniere tres similaire : 

maZone = uneFeui 1 1 e . getCel 1 RangeByName("B2 : AF10") 
maZone = uneFeui 1 1 e . getCel 1 RangeByName("zoneVal eurs") 
maZone = uneFeuille.getCellRangeByPosition(l,l, 31,9) 

Dans la premiere maniere, vous reconnaissez la definition d'une zone dans Calc. La 
deuxieme utilise une zone nommee situee dans la feuille. La troisieme maniere utilise 
une nouvelle methode qui prend quatre arguments : les coordonnees de deux cellules 
constituant les coins haut gauche et bas droite de la zone, de la forme (X1,Y1,X2,Y2) 
designant respectivement les coordonnees de la premiere puis de la deuxieme cellule. 

Notez qu'une zone de plusieurs cellules est un type d'objet different d'un objet cellule, bien que les deux 
aient de nombreuses proprietes identiques. En revanche, une zone d'une seule cellule est un objet cellule. 



Nous pouvons parfaitement recuperer une cellule en se reperant en relatif par rapport 
a l'interieur d'une zone de cellules. II suffit d'utiliser la methode getCellByPosition 
de l'objet zone de cellules. 

rem Code09-01.ods bibli : ZonesCel 1 ul es Module2 
Option Explicit 

Sub TrouverCel 1 ul edeZone() 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maCellule As Object, maZone As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Janvi er") 

' trois manieres d' obtenir la meme zone 

'maZone = maFeui 1 1 e . getCel 1 RangeByName("B2 : AF10") 

'maZone = maFeui 1 1 e . getCel 1 RangeByName("zoneVal eurs") 

maZone = maFeuille. getCellRangeByPosition(l,l, 31,9) 

' recuperer la cellule C2 

maCellule = maZone. getCellByPosition (1,0) 

print "Acces par position XY d'une zone = " & maCel 1 ul e . val ue 
End Sub 

La cellule de coordonnees C2 est situee sur la deuxieme colonne et la premiere ligne de 
la zone B2 : AF10, done ses coordonnees XY relatives a la zone sont 1 et 0. De la meme 
maniere, on pourrait definir une autre zone de cellules a l'interieur de la premiere zone, 
en utilisant getCel 1 RangeBy Posi ti on avec des coordonnees XY relatives. 
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A l'inverse, getCell RangeByName utilise toujours des coordonnees absolues, meme si 
vous utilisez cette methode a partir d'un objet zone. 

Obtenir les coordonnees d'une cellule 

Disposant d'une cellule quelconque, par exemple obtenue dynamiquement, on 
obtient ses coordonnees absolues grace a sa propriete CellAddress, qui renvoie une 
structure Cell Address decrite au tableau 9-1. 



Tableau 9-1 Structure CellAddress 





Sheet 


Integer 


Rang de la feuille dans le classeur, numerate a partir de zero. 


Col umn 


Long 


Rang de colonne (X) dans la feuille, numerate a partir de zero. 


Row 


Long 


Rang de ligne (Y) dans la feuille, numerate a partir de zero. 



Nous avons precedemment indique comment obtenir une feuille a partir de son rang, 
puis obtenir le nom de la feuille. Cependant, nous pouvons obtenir plus directement 
l'objet feuille dans lequel se trouve la cellule : 



uneFeuille = maCell ul e . Spreadsheet 

La propriete Absol uteName de la cellule renvoie ses coordonnees sous forme texte en 
adressage absolu, exemple : 

maCellule = maFeuille.getCellByPosition(31,9) 

print maCellule. Absol uteName' affiche : $Feuillel.$AF$10 

Certaines methodes de l'API utilisent en argument un objet coordonnees de cellule. 
II se definit soit a partir d'une cellule et de sa propriete CellAddress, soit 
directement : 

Dim cooCell As New com. sun. star. table. Cell Address 

' cellule feuille2.H14 

cooCell .Sheet = 1 ' deuxieme feuille du document tableur 
cooCel 1 . Col umn = 7 ' colonne H 
cooCell. Row = 13 ' ligne 14 

L' annexe B offre plusieurs fonctions utilitaires liees a l'adressage vu par l'utilisateur : 
• adresseStri ng convertit une adresse de type Cell address en adresse textuelle, 
exemple "Feuille2.B17" ; 
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nomColonne renvoie le nom d'une colonne a partir de son rang, par exemple la 
valeur 19 donne "T" ; 

indexColonne renvoie le rang d'une colonne a partir de son nom, par exemple 
"BH" donne la valeur 59. 



Obtenir les coordonnees d'une zone de cellules 

De maniere similaire, une zone de cellules nous donne ses coordonnees absolues 
grace a sa propriete RangeAddress, qui renvoie une structure Cell RangeAddress 
decrite au tableau 9-2. 



Tableau 9-2 Structure CellRangeAddress 



Propriete 


Type Signification 


Sheet 


Integer 


Rang de la feuille dans le classeur, numerate a partir de zero. 


StartCol umn 


Long 


Rang de colonne (X1) de la cellule du coin haut-gauche de la zone, nume- 
rate a partir de zero. 


StartRow 


Long 


Rang de ligne (Y1) de la cellule du coin haut-gauche de la zone, numerate 
a partir de zero. 


EndCol umn 


Long 


Rang de colonne (X2) de la cellule du coin bas-droite de la zone, numerate 
a partir de zero. 


EndRow 


Long 


Rang de ligne (Y2) de la cellule du coin bas-droite de la zone, numerate a 
partir de zero. 



L'objet feuille dans lequel se trouve la zone est obtenu directement : 



uneFeuille = maZone . Spreadsheet 

La propriete Absol uteName de la zone renvoie ses coordonnees sous forme texte en 
adressage absolu, exemple : 

maZone = maFeuille.getCellRangeByPosition(l,l, 31,9) 
print maZone. Absol uteName' affiche : $Feui 1 lei. $B$2 : $AF$10 

Un objet coordonnees de zone de cellules peut aussi etre defini directement : 

Dim cooZone As New com. sun. star. table. Cell RangeAddress 

' zone feuille2.H14:L23 

cooZone . Sheet = 1 ' deuxieme feuille du document tableur 
cooZone. StartCol umn = 7 ' colonne H 
cooZone . StartRow = 13 ' ligne 14 
cooZone . EndCol umn = 11 1 colonne L 
cooZone . EndRow = 22 ' ligne 23 
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La routine adrZoneStri ng de l'annexe B convertit une adresse de type RangeAddress 
en adresse sous forme de chaine de caracteres. 

Nous utiliserons ces notions avec les selections visuelles. 



Les zones nominees 

Dans la macro qui suit, nous allons recuperer la liste des zones nominees d'un docu- 
ment Calc, ajouter une zone nommee puis la supprimer. Les zones nominees sont 
contenues dans l'objet NamedRanges du document. Le nombre de zones est obtenu 
avec sa propriete Count. On peut acceder a une des zones par son numero d'ordre 
avec la methode getBylndex. Avec OOoBasic, le getBylndex peut etre omis, comme 
si on indexait une variable tableau. Le document de l'archive Zip telechargeable con- 
tient plusieurs zones nominees. D'autres explications sont donnees apres la macro. 

rem Code09-01.ods bibli : ZonesCellules Module5 
Option Explicit 

Sub NommerZoneO 

Dim monDocument As Object, lesFeuilles As Object 
Dim maFeuille As Object, maCellule As Object 
Dim lesZonesNom As Object, maZoneNom As Object, x As Long 
Const unNom = "Genre de depense" 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
maFeuille = 1 esFeui 11 es . getByName(" Janvi er") 
maCellule = maFeui 1 1 e . getCel 1 RangeByName("C2") 
lesZonesNom = monDocument . NamedRanges 
for x = 0 to lesZonesNom. Count -1 
maZoneNom = lesZonesNom (x) 

print "Zone n°" & x , maZoneNom . Name , "", maZoneNom. Content 

next 

if not lesZonesNom. hasByName(unNom) then 

lesZonesNom. addNewByName(unNom , "Janvier. A2 :A7" , _ 

maCellule. Cell Address, 0) 
print "Nouvelle zone nommee : " & unNom 

end if 

if MsgBox("Effacer I'exemple " & unNom & " ?", 4) = 6 then 

1 esZonesNom . r emoveByName (unNom) 
end if 
End Sub 

Chaque zone comporte deux proprietes de type Stri ng : 
• Name contient le nom de la zone. 
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• Content contient dans notre exemple une adresse de zone, mais pourrait aussi 
bien contenir une formule avec des adresses ; les adresses peuvent etre absolues, 
relatives, ou partiellement relatives. 

Avant d'ajouter un nom de zone, nous devons nous assurer qu'il n'existe pas deja, 
grace a la fonction hasByName de l'objet TesZonesNom. La methode addNewByName, du 
meme objet, utilise quatre parametres : 

1 le nom de la nouvelle zone ; 

2 la definition de la zone, ici une simple adresse, mais eventuellement une formule ; 

3 une adresse de cellule servant de reference, qui doit se situer dans la meme feuille ; 

4 le type de la zone, zero dans la plupart des cas. 

Pourquoi une adresse de cellule de reference ? Nous pouvons tres bien utiliser une 
zone nommee dans une formule d'une cellule quelconque, ou la zone peut etre elle- 
meme une formule qui sera stockee dans une cellule. Dans ces cas, si la definition 
contient des adresses relatives, elles seront mises a jour en fonction des positions rela- 
tives. Dans la feuille Janvier, nous avons mis la formule =SOMME(GenreDepense) 
dans la cellule C16. Tant que la zone de ce nom n'est pas definie, la cellule affiche une 
erreur. Quand la zone est definie par la macro, elle affiche la somme des 
cellules A16:A20. 

Enfin, l'objet TesZonesNom offre la methode removeByName, qui nous permet de sup- 
primer une zone nommee. 

Pour plus d'information sur les zones nominees, consulter le Developer's Guide a la sec- 
tion Spreadsheet Documents> Working with Spreadsheet Documents>Navigating>Named 
Ranges et les interfaces XNamedRanges et XnamedRange dans la documentation API. 

Les selections visuelles 

Selection faite par I'utilisateur 

L'utilisateur peut selectionner une cellule, une zone de cellules, ou meme plusieurs 
zones, puis appeler une macro qui fera un traitement en fonction de ces zones. 
L'objet CurrentSelection obtenu du document nous donne des informations sur la 
selection, mais d'une maniere complexe car la nature de cet objet est differente dans 
chaque cas. 

La distinction se fera en recherchant quels services sont supportes par 
CurrentSelection, grace a sa fonction supportsServi ce, qui renvoie True si le ser- 
vice en argument est reconnu. La macro suivante, que nous allons expliquer, affiche 
les coordonnees de chaque zone selectionnee. Nous utilisons des routines de 
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l'annexe B qui sont recopiees dans le module Utilitaires de la bibliotheque 
Standard du meme document. 

rem Code09-01 . ods bibli : ZonesCellules Module3 
Option Explicit 

Sub Affi cherCoordonneesSelectionO 

Dim monDocument As Object, lesFeuilles As Object 

Dim sel As Object, coord As Object 

Dim x As Long, zonex As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

sel = monDocument . CurrentSel ecti on 
if sel .supportsServiceC 

"com . sun . star . sheet . SheetCel 1 Ranges") then 
for x = 0 to sel .Count -1' balayer les zones 
zonex = sel (x) 

MsgBox "Zone n°" & x & " = " & _ 

adrZoneStri ng (monDocument , zonex . RangeAddress) 

next 

elseif sel .supportsService("com. sun. star. table. Cell") then 
coord = sel .Cell Address ' une seule cellule selectionnee 
MsgBox "Une cellule = " & adresseStri ng(monDocument , coord) 

elseif sel .supportsService("com. sun. star. table. CellRange") then 

MsgBox "Une seule zone = " & _ 

adrZoneStri ng(monDocument , sel .RangeAddress) 

el se 

MsgBox("Erreur logicielle !", 16) 
end if 
End Sub 

Les tests successifs sur les services reconnus doivent etre faits dans l'ordre indique, 
car une seule cellule reconnait aussi le service Cel 1 Range. 

Attention a la casse ! Les noms de services doivent etre ecrits en respectant les 
majuscules et minuscules. 

Si plusieurs zones sont selectionnees, l'objet obtenu par CurrentSel ecti on fournit 
leur nombre avec sa propriete Count. On peut acceder a une des zones par son 
numero d'ordre avec la methode getBylndex. Avec OOoBasic, le getBylndex peut 
etre omis, comme si on indexait une variable tableau. En utilisant les proprietes de 
coordonnees de zone decrites plus haut, et a l'aide de la routine adrZoneStri ng de 
l'annexe B, nous affichons les coordonnees de chaque zone. 

Si nous n'avons qu'une seule zone, celle-ci est directement disponible. Si une cellule 
seulement est selectionnee (ou simplement si le curseur est sur une cellule), la cellule 
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est directement disponible et nous affichons ses coordonnees avec la routine 
adresseStri ng de l'annexe B. 

Cette macro nous donne l'occasion de faire deux manipulations interessantes : 

• Cliquez sur la feuille dans la case en coin haut-gauche des coordonnees, pour 
selectionner toute la feuille ; affichez les coordonnees. 

• Selectionnez un grand rectangle de cellules. Avec la touche Ctrl appuyee, cliquez 
sur quelques cellules au hasard : votre selection est maintenant « trouee ». Affi- 
chez les coordonnees : vous constaterez que votre selection est definie par un 
nombre de zones rectangulaires suffisant pour la couvrir. 

Afin de travailler sur plusieurs feuilles a la fois (normalement ayant la meme struc- 
ture), i'utilisateur peut selectionner plusieurs feuilles. Dans le document exemple, cli- 
quez sur l'onglet Sommaire, puis faites un Ctrl + clic sur l'onglet Contenus : ces deux 
feuilles sont selectionnees simultanement. Selectionnez une ou plusieurs zones sur la 
feuille visible, et executez encore la macro. Vous verrez que chaque zone a ete selec- 
tionnee dans chacune de ces feuilles. Pour deselectionner les feuilles, faites un 
Maj + die sur l'onglet de la feuille visible. 

Afficher une zone selectionnee 

Afficher dans la fenetre Calc une zone de cellules selectionnee est bien plus simple. 
On transmet a la methode select du controleur du document un objet cellule ou un 
objet zone de cellules. 

rem Code09-01.ods bibli : ZonesCel 1 ul es Module4 
Option Explicit 

Sub Affi cherZoneSel ecti onnee() 

Dim monDocument As Object, lesFeuilles As Object 
Dim maFeuille As Object, maCellule As Object 
Dim maZone As Object 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
maFeuille = 1 esFeui 1 1 es . getByName("Janvi er") 
maZone = maFeui 1 1 e . getCell RangeByName("E5 : F7") 
monDocument . Cu r rentCont rol 1 er . sel ect (maZone) 
End Sub 

Si le tableur affichait une autre feuille, celle contenant la selection devient visible. 
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Zone visible dans la feuille 

Figer des lignes ou colonnes 

Le menu Fenetre>Fixer permet de maintenir la vision des en-tetes d'un tableau depas- 
sant la taille de la feuille. Ceci est realise par programmation avec la methode 
f reezeAtPosition de l'objet controleur du tableur ; elle prend en argument le 
nombre de colonnes et de lignes a figer. Pour debloquer ce type d'affichage, il est 
necessaire que la cellule active soit en position Al. 

rem Code09-01.ods bibli : Feuilles Module9 
Option Explicit 

Sub FigerLignesColonnesO 

Dim monControleur As Object, maFeuille As Object, position As Object 

monControleur = Thi sComponent . CurrentControll er 

if MsgBox("Figer 3 lignes et 2 colonnes ?", 4) = 6 then 

monControl eur . f reezeAtPosi tion(3 , 2) 
el se 

maFeuille = monControleur. ActiveSheet 

position = maFeuille. getCel 1 RangeByName("Al") 

monControl eur . sel ect (posi ti on) 

monCont rol eur. f reezeAtPosi t ion (0 , 0) 
end if 
End Sub 

Premiere ligne et premiere colonne affichees 

Sur une feuille trop grande pour etre affichee en totalite, vous pouvez choisir les 
coordonnees de la cellule qui sera affichee dans le coin gauche, en haut. 

Dim monDocument As Object, monControleur As Object 
monDocument = Thi sComponent 

monControleur = monDocument. CurrentController 
' choisir la feuille a afficher - ici la deuxieme 
monControleur. ActiveSheet = monDocument. Sheets(l) 
monControleur.FirstVisibleColumn = 17 1 colonne R 
monControleur. FirstVisibleRow = 153 1 ligne 154 

Inversement, vous pouvez connaitre les coordonnees de la premiere cellule affichee 
en lisant la valeur de ces deux proprietes. De plus l'objet controleur expose la pro- 
priete VisibleRange qui est une structure de type Cell RangeAddress deja vue a la 
section « Obtenir les coordonnees d'une cellule ». Cette propriete, en lecture seule, 
vous donne les coordonnees extremes de l'ensemble des cellules affichees. 
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Proprietes globales de la cellule 

Une zone de cellules possede presque toutes les proprietes d'une cellule, ce qui permet 
de modifier en une instruction toutes les cellules de la zone de maniere identique. 

Proteger une cellule 

La protection d'une cellule n'est activee que lorsque la feuille est protegee. Nous 
avons decrit plus haut comment proteger une feuille. La propriete Cell Protection 
d'une cellule renvoie une structure UNO decrite dans le tableau 9-3. Pour modifier 
un des elements, vous devez passer par une variable intermediate. Effectuez la 
modification de Cell Protection avec la feuille non protegee, puis protegez la feuille. 



Tableau 9-3 Structure CellProtection 





IsLocked 


Boolean 


True 


True pour interdire les modifications. 


IsFormul aHi dden 


Bool ean 


Fal se 


True pour cacher la formule. 


IsHidden 


Bool ean 


Fal se 


True pour cacher la cellule. 


IsPri ntHi dden 


Boolean 


Fal se 


True pour ne pas imprimer la cellule. 



Dans cet extrait de macro, la variable 1 aProtecti on etant declaree dans Basic comme 
une structure UNO, toutes ses valeurs sont a False, et seule IsFormul aHi dden est 
modifiee : 



rem Code09-01.ods bibli : Protection Module3 

Dim laProtection As New com. sun. star. util .CellProtection 

1 aProtecti on. IsFormul aHi dden = True 

maCellule. CellProtection = laProtection 

maFeuille.protect("OpenOffice") ' mettre un mot de passe 

On aurait pu charger la valeur actuelle de Cel 1 Protection dans une variable objet, la 
modifier puis la copier dans Cel 1 Protection. 

Le style de la cellule 

Le plus rapide pour formater une cellule est d'utiliser un style de cellule deja defini 
dans le document. La propriete Cel 1 Styl e est une chaine de caracteres qui contient 
le nom du style. On peut facilement changer le nom du style en cours : 



print maCellule. Cell Style 

maCel 1 ul e . Cel 1 Styl e= "MonStyl eAMoi " 
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Attention a la casse ! Les noms de styles doivent etre ecrits en respectant les majuscules et minuscules. 



On peut modifier de la meme maniere le style d'une zone de cellules. 

Inversement, la propriete Cel 1 Styl e fournit le nom du style de la cellule. Pour une 
zone comportant plusieurs styles, la propriete Cell Style fournira une chaine de 
caracteres nulle. 



PlEGE Les noms de styles traduits 

Pour les styles standards fournis avec OpenOffice.org, vous recuperez dans Cel 1 Styl e le nom anglais 
du style, meme avec une version francisee. Par exemple, en affectant le style « Standard » on relira le 
nom de style « Default ». En revanche, les styles que vous creez n'ont evidemment qu'un seul nom. 
L'annexe B offre une fonction getLocal eStyl eName, qui traduit un nom de style anglais dans son 
nom localise. 



Les proprietes que nous allons voir maintenant concernent l'ensemble de la cellule ; 
les modifier n'entraine pas une modification du style de la cellule. De plus, une inter- 
rogation du style de la cellule donnera toujours le meme nom alors que cette derniere 
aura change d'aspect. 

Aspect general 

Le tableau 9-4 montre la liste des proprietes simples concernant 1' aspect d'une cel- 
lule. Nous verrons ensuite separement les autres proprietes. 

Tableau 9-4 Proprietes simples d'aspect de cellule 



Propriete 


Type 


Signification 


Spreadsheet 


Object 


La feuille a laquelle appartient la cellule. 


CellBackColor 


Long 


Couleur du fond. 


IsCel 1 BackgroundTransparent 


Boolean 


True si la couleur de fond n'est pas utilisee. 


IsTextWrapped 


Boolean 


True si le texte est automatiquement renvoye a la ligne au bord 
droit de la cellule. 

Fal se si le texte reste sur une seule ligne (I'affichage peut etre 
tronque). Valeur par defaut. 


Shri nkToFi t 


Boolean 


True pour ajuster automatiquement la tail le de la police pour 
que le texte tienne dans la cellule. 


Paralndent 


Integer 


Retrait du contenu par rapport au bord gauche de la cellule, 
en 1/100 de mm. 


ParaTopMargi n 


Long 


Marge du haut, en 1 /1 00 de mm. 


ParaBottomMargi n 


Long 


Marge du bas, en 1/100 de mm. 
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Tableau 9-4 Proprietes simples d'aspect de cellule (suite) 



Propriete Type Signification 


ParaLeftMargi n 


Long 


Marge de gauche, en 1 /1 00 de mm. 


ParaRi ghtMargi n 


Long 


Marge de droite, en 1/100 de mm. 



Exemple : 



rem Code09-02 . ods bibli : Formater Module5 
Option Explicit 

Sub FormaterCell ul e() 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maCellule As Object, monCurseur As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Feui 11 e2") 

maCellule = maFeuille. getCell RangeByName("F16") 

maCellule. Cell BackCol or = RCB(100 , 220 , 220) 
maCellule.ParaLeftMargin = 200 ' 2 mm de marge gauche 
End Sub 



Formater des caracteres 

L'objet cellule accepte la plupart des nombreuses proprietes de caractere disponibles 
que nous avons decrites au chapitre 8 consacre a Writer. Lorsque vous utilisez ces 
proprietes sur l'objet cellule, le formatage s'appliquera a l'ensemble des caracteres 
affiches dans la cellule. Nous verrons plus loin comment utiliser un curseur d'ecriture 
pour formater certains caracteres dans la cellule. 

Une zone de cellules supporte les memes proprietes de formatage. 
Format d'affichage 

Le format d'affichage d'un nombre dans une cellule depend de sa propriete 
NumberFormat, de type Long. Cette valeur est un index dans la collection des formats 
disponibles dans le document. Ce concept est decrit au chapitre 7 a la section « Les 
formats de nombre ». 



Alignement horizontal 

La propriete Hori Justify, de type Integer, regie l'alignement horizontal du con- 
tenu de la cellule. On lui affecte une des quatre constantes nominees suivantes : 
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com. sun. star. table. Cell Horn Justify. STANDARD ' par defaut 

com. sun. star. table. CellHori Justify. LEFT ' a gauche 

com. sun. star. table. CellHori Justify. CENTER ' centre 

com. sun. star. table. CellHori Justify. RIGHT ' a droite 

Attention a la casse ! Les constantes nominees doivent etre ecrites en respectant les 
majuscules et minuscules. 

La valeur par defaut aligne a gauche pour un nombre, a droite pour un texte. 
Alignement vertical 

La propriete Vert Justify, de type Integer, regie 1' alignement vertical du contenu 
de la cellule. On lui affecte une des quatre constantes nominees suivantes : 

com. sun. star. table. Cell Vert Justi fy . STANDARD ' par defaut 

com. sun. star. table. Cell Vert Justi fy . TOP ' en haut 

com. sun. star. table. Cell Vert Justi fy . CENTER ' centre 

com. sun. star. table. Cell VertJusti fy . BOTTOM ' en bas 

Lalignement vertical apparait si la hauteur de la cellule (ou la ligne) est nettement 
plus grande que celle des caracteres dans la cellule. 

Orientation du contenu 

Plusieurs proprietes gouvernent l'orientation du texte de la cellule, voyez le 
tableau 9-5. Exemple : 

maCel 1 ul e . Ori entati on = com . sun . star . tabl e . Cell Ori entati on . TOPBOTTOM 
maCel 1 ul e . RotateRef erence = com . sun . star . tabl e . Cel 1 Vert Justi f y . BOTTOM 

Tableau 9-5 Proprietes de rotation du texte 
Element Type Signification 



RotateAngle 


Long 


Angle de rotation, en 1/100 de degre. Une valeur positive correspond au sens 
trigonometrique (le sens inverse des aiguilles d'une montre). 


Orientation 


Integer 


Valide seulement si RotateAngl e vaut zero. Contient une constante nommee 
(tableau 9-6) de la forme : 

com . sun . star . tabl e . CellOri entati on . STANDARD 


RotateReference 


Integer 


Precise sur quel bord de la cellule le texte est aligne. Contient une constante 
nommee de la meme liste que pour I'alignement vertical. 
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Tableau 9-6 Constantes d'orientation du contenu de cellule 



Zonstante 



STANDARD 


Par defaut (de gauche a droite pour le francais). 


TOP BOTTOM 


Pour lire, pencher la tete a droite. 


BOTTOMTOP 


Pour lire, pencher la tete a gauche. 


STACKED 


Chaque lettre est horizontale, les lettres sont placees de haut en bas comme 
une enseigne. 



Ombre de la cellule 

La propriete Shadow/Format est une structure comportant plusieurs elements, voyez le 
tableau 9-7. 

Tableau 9-7 Structure de ShadowFormat 



Location 


Integer 


Position de I'ombre, sous forme de constante nommee, voir 
tableau 9-8. 


ShadowWi dth 


Integer 


Largeur de I'ombre, en 1/100 de mm. 


IsTransparent 


Boolean 


True si I'ombre est transparente. 


Color 


Long 


Couleurde I'ombre. 



La position de I'ombre est exprimee sous forme de constante nommee (tableau 9-8), 
de la forme : 

com . sun . star . tabl e . ShadowLocati on . BOTTOM RIGHT 

Tableau 9-8 Constantes de position d'ombre de cellule 



NONE 


Aucune ombre. 


TOP_LEFT 


Ombre portee vers le haut et a gauche. 


TOP_RIGHT 


Ombre portee vers le haut et a droite. 


BOTTOM_LEFT 


Ombre portee vers le bas et a gauche. 


BOTTOM_RIGHT 


Ombre portee vers le bas et a droite. 



II est necessaire de remplir la structure dans une variable de travail qui servira a ini- 
tialiser ShadowFormat comme ici : 



rem Code09-02 . ods bibli : Formater Module3 
Option Explicit 
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Sub OmbreDeCelluleO 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maCellule As Object 

Dim ombre As New com . sun . star . tab! e . Shadow/Format 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = lesFeuilles. getByName("Feuille2") 

maCellule = maFeuille.getCellRangeByName("E2") 

ombre. Location = com. sun. star. table. ShadowLocation. TOP LEFT 

ombre. Shadow/Width = 200 ' environ 3,5 mm 

ombre. Color = RGB (100 , 100 , 100) ' couleur grise 

maCellule. Shadow/Format = ombre 

End Sub 

Pour bien voir l'ombre, il est preferable que la cellule soit encadree ou ressorte avec 
une couleur de fond. 



Bordures et diagonales de la cellule 

Une cellule comporte quatre bords et deux diagonales. Le tableau 9-9 liste les pro- 
prietes correspondantes. Chacune contient une structure dont les elements sont listes 
au tableau 9-10. 

Tableau 9-9 Bordures et diagonales d'une cellule 



TopBorder 


Object 


Bordure du haut. 


BottomBorder 


Object 


Bordure du bas. 


LeftBorder 


ObjectH 


Bordure de gauche. 


Ri ghtBorder 


Object 


Bordure de droite. 


Di agonal BLTR 


Object 


Diagonale du coin en bas a gauche au coin en haut a droite. 


DiagonalTLBR 


Object 


Diagonale du coin en haut a gauche au coin en bas a droite. 


Tableau 9-10 Structure BorderLine (ligne de bordure) 






Signification 


Color 


Long 


Couleur de la ligne. 


InnerLi neWidth 


Integer 


Epaisseur de la ligne interne, en 1 /1 00 de mm, dans le cas d'une bor- 
dure double. La valeur zero correspond a une bordure simple. 


OuterLi neWidth 


Integer 


Epaisseur de la ligne simple, ou de la ligne externe dans le cas d'une 
bordure double ; en 1 /1 00 de mm. La valeur zero correspond a une 
bordure inexistante. 


Li neDi stance 


Integer 


Distance entre les deux lignes d'une bordure double, en 1/100 
de mm. 
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Un exemple est plus explicite : 

rem Code09-02 . ods bibli : Formater Modulel 
Option Explicit 

Sub BorduresDeCelluleO 

Dim monDocument As Object, lesFeuilles As Object 
Dim maFeuille As Object, maCellule As Object 
Dim unBord As New com. sun. star. table. Border Line 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
maFeuille = 1 esFeui 1 1 es . getByName("Feui 11 e2") 
maCellule = maFeui 11 e . getCell RangeByName("C2") 
With unBord ' utilisez le zoom a 200% ! 

.Color = RCB(200,0,0) 

.OuterLineWidth = 30 

maCellule. LeftBorder = unBord' ligne simple, rouge 
.OuterLineWidth = 100 

maCellule.RightBorder = unBord ' ligne simple, rouge 
. InnerLineWidth = 60 
. Li neDi stance = 30 
.Color = RGB(0, 120,0) 

maCellule.TopBorder = unBord ' ligne double, verte 
.Color = RGB(0, 0,120) 

maCell ul e . BottomBorder = unBord ' ligne double, bleue 

.InnerLineWidth = 0 

.OuterLineWidth = 50 

. Li neDi stance = 0 

.Color = RGB(100,100,100) 

maCellule. Di agonal BLTR = unBord ' ligne simple, grise 
End With 
End Sub 



Note ou annotation de cellule 

La note d'une cellule est obtenue avec la propriete Annotation, qui renvoie un objet 
exposant plusieurs pseudo-proprietes listees dans le tableau 9-11. Cette propriete 
Annotation n'existe pas pour une zone de cellules. 



Tableau 9-11 Elements d'une note de cellule 





Stri ng 


Stri ng 


Texte de la note. 


Author 


Stri ng 


Auteur de la note. Lecture seulement. 


Date 


Stri ng 


Date de creation de la note. Lecture seulement. 


IsVisible 


Boolean 


True si la note est affichee en permanence. 

Fal se si la note ne s'affiche qu'au passage de la souris. 
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Tableau 9-11 Elements d'une note de cellule (suite) 





Position 


Object 


Position de la cellule qui contient cette note ; structure Cel 1 Address, voir 
le tableau 9-1 . Lecture seulement. 


Parent 


Object 


La cellule a laquelle est rattachee la note. 



Si la cellule ne comporte pas de note, les proprietes String, Author et Date contien- 
nent des chaines nulles. La macro ci-dessous illustre ces proprietes. 



rem Code09-02 . ods bibli : Annoter Modulel 
Option Explicit 

Sub LireNoteO 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 

Dim maCellule As Object, laNote As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 11 es . getByName("Feui 11 e3") 

maCellule = maFeui 1 1 e . getCel 1 RangeByName("D57") 

laNote = maCellule. Annotation 

voirLeContenuDeLaNote(l aNote) 

if MsgBox("Changer le texte de la note ?", 4) = 6 then 
laNote. String = "Note modifiee le" & chr(13) & Now 
end if 
End Sub 

Sub voi rLeContenuDeLaNote(l aNote As Object) 

Dim cr As String 

cr = chr(13) ' fin de ligne 

if Len (laNote. Date) = 0 then 

MsgBox("La cellule ne contient pas de note", 16) 
el se 

MsgBox("Auteur de la note : " & laNote. Author & cr & _ 

"Date de la note : " & laNote. Date & cr & _ 

"Visible en permanence : " & 1 aNote . IsVi si bl e & cr & _ 

"Contenu de la note : " & cr & 1 aNote . String , _ 

0, "Cellule : " & 1 aNote . Parent .Absol uteName) 
end if 
End Sub 

Le contenu de la note est affiche avec un petit sous-programme que nous reutilise- 
rons. Pour afficher l'adresse de la cellule contenant la note, le plus simple est de 
remonter a la cellule avec Parent et d'utiliser la propriete Absol uteName. II est pos- 
sible de definir un curseur d'ecriture pour ecrire le texte d'une note mais, en l'absence 
de possibilites de formatage et compte tenu de l'habituelle simplicite des notes, il est 
plus simple de manipuler directement la propriete String. 
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Les notes qui existent dans une feuille se trouvent dans la collection Annotations 
(attention au s) de la feuille. La macro suivante va enumerer les notes presentes avec 
un index. 

rem Code09-02 . ods bibli : Annoter Module2 
Option Explicit 

Sub ListerNotesO 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 

Dim lesNotes As Object, laNote As Object, x As Long 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Feui 11 e3") 

lesNotes = maFeui lie. Annotations 

for x = 0 to lesNotes. Count -1 

laNote = lesNotes(x) 

voi rLeContenuDeLaNote(laNote) 
next 
End Sub 

Les notes de cellule ont ete remaniees dans la version 2.02 d'OpenOffice.org pour 
permettre le formatage du texte (par l'utilisateur, mais pas par l'API, voir 
Issue 96587). Ceci a provoque un bogue dans la creation de notes par programma- 
tion, corrige seulement depuis la version 3.1. Le codage qui suit necessite au moins 
cette version. 

rem Code09-02 . ods bibli : Annoter Module3 
Option Explicit 

Sub creerNoteO 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 

Dim maCellule As Object, lesNotes As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Feui 11 e3") 

maCellule = maFeui 11 e . getCell RangeByName("C13") 

lesNotes = maFeui 11 e .Annotations 

lesNotes. insertNew(maCellule. Cell Address, "Une nouvelle note") 

End Sub 

On utilise la methode insertNew de l'objet Annotations afin de creer la note. Le 
premier argument est la structure Cell Address correspondant a la cellule, le 
deuxieme argument est le texte de la note. Les proprietes d'auteur et de date sont en 
lecture seule, elles sont remplies automatiquement. 
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Pour supprimer la note d'une cellule, on utilise la methode removeBylndex de l'objet 
Annotations. Partant de la cellule, nous devons retrouver la note en balayant la col- 
lection, ce qui nous donne la valeur d'index correspondante. 

rem Code09-02 . ods bibli : Annoter Module4 
Option Explicit 

Sub supprimerNoteO 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 
Dim maCellule As Object, lesNotes As Object, positionNote As String 
Dim x As Long, uneNote As Object 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
maFeuille = lesFeuilles.getByName("Feuille3") 
maCellule = maFeui 1 1 e . getCel 1 RangeByName("C13") 
positionNote = maCellule.AbsoluteName 
lesNotes = maFeuille. Annotations 
for x = 0 to lesNotes. Count -1 
uneNote = lesNotes(x) 

if uneNote. Parent. Absol uteName = positionNote then 
1 esNotes . removeBylndex(x) 

Exit For 
end if 
next 
! End Sub 



Bordures d'un tableau 

Ici, on appelle tableau une zone rectangulaire de plusieurs cellules. Pour l'encadrer et 
quadriller l'interieur, inutile de remplir patiemment les bordures de toutes les 
cellules : on utilise la propriete TableBorder d'un objet zone de cellules. Cette der- 
niere est une structure (voir tableau 9-12) dont chaque descripteur de ligne (TopLi ne, 
LeftLi ne, etc.) est lui-meme la structure deja decrite au tableau 9-10. 



Tableau 9-12 Structure de TableBorder 



Element 






IsTopLineValid 


Boolean 


Validation de la bordure du haut, voirtexte. 


TopLi ne 


Object 


Description de la bordure du haut. 


IsBottomLi neVal i d 


Boolean 


Validation de la bordure du bas, voir texte. 


BottomLi ne 


Object 


Description de la bordure du bas. 


IsLeftLineValid 


Boolean 


Validation de la bordure de gauche, voir texte. 


LeftLi ne 


Object 


Description de la bordure de gauche. 


IsRightLineValid 


Boolean 


Validation de la bordure de droite, voir texte. 
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Tableau 9-12 Structure de TableBorder (suite) 



Element Type Signification 


RightLi ne 


Object 


Description de la bordure de droite. 


IsHori zontal Li neVal i 
d 


Bool ean 


Validation des lignes horizontales interieures, voir texte. 


Horn zontal Li ne 


Object 


Description des lignes horizontales interieures. 


IsVerti cal Li neVal i d 


Bool ean 


Validation des lignes verticales interieures, voir texte. 


Verti cal Li ne 


Object 


Description des lignes verticales interieures. 


IsDistanceValid 


Boolean 


True si I'ecart avec le contenu est utilise. 


Distance 


Integer 


Ecart avec le contenu, en 1/1 00 de mm, pour toutes les bor- 
dures. 



Le reglage d'un ecart avec le contenu different suivant les bordures ne semble ni rea- 
lisable ni visible a travers l'API. La propriete Distance correspond a I'ecart 
synchronise du panneau d'interface utilisateur. 

Les proprietes Is . . . Val i d ont une signification subtile. 

• En lecture, un tel indicateur indique True si la structure Li ne correspondante est 
valable sur toute la longueur de la ligne ; il indique Fal se si la structure de la ligne 
varie le long des cellules qui la constituent. 

• En ecriture, la signification est totalement differente : employez la valeur True 
pour modifier la structure Line correspondante, employez la valeur False pour 
garder la valeur actuelle de la structure Li ne correspondante (dans l'affectation de 
la nouvelle valeur de TableBorder, la structure Line correspondante ne sera done 
pas prise en compte). 

Les proprietes IsHori zontal Li neVal id et IsVerti cal Li neVal id traitent toutes les 
lignes du quadrillage interieur. 

• En lecture, la valeur True indique que toutes les lignes de ce type ont les memes 
valeurs de bordure. 

• En ecriture, la valeur True indique que toutes les lignes de ce type doivent prendre 
la meme valeur de bordure. 

Modifier une bordure necessite d'utiliser des variables intermediaires pour acceder 
aux structures. Void un exemple qui cree des bordures et un quadrillage de tableau. 

rem Code09-02 . ods bibli : Formater Module2 
Option Explicit 

Sub BorduresDeTableauO 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maZone As Object, lesBords As Object 
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Dim unBord As New com. sun. star .table. Border Line 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = lesFeuilles. getByName("Feuille2") 

maZone = maFeui 11 e . getCell RangeByName("B4 : D8") 

lesBords = maZone.TableBorder 

With unBord' utilisez le zoom a 200% ! 

.Color = RGB(200,0,0) 

.OuterLineWidth = 30 

1 esBords . LeftLine= unBord ' ligne simple, rouge 
.OuterLineWidth = 100 

lesBords. RightLine = unBord ' ligne simple, rouge 
.OuterLineWidth = 30 

.Color = RGB(220, 220,0) ' quadrillage de lignes jaunes 

lesBords. VerticalLine = unBord 

lesBords. Horizontal Line = unBord 

.InnerLineWidth = 60 

. Li neDi stance = 30 

.Color = RGB(0, 120,0) 

lesBords. TopLine = unBord ' ligne double, verte 
.Color = RGB(0, 0,120) 

lesBords. BottomLine = unBord ' ligne double, bleue 
End With 
With lesBords 

. IsBottomLi neVal i d = true 

.IsTopLineValid = true 

.IsLeftLineValid = true 

.IsRightLineValid = true 

.IsHorizontalLineValid = true 

.IsVerticalLineValid = true 
End With 

maZone.TableBorder = lesBords 
End Sub 

Une zone de cellules expose aussi les proprietes deja vues pour les bordures et diago- 
nals d'une cellule. Elle s'appliquent alors a chaque cellule de la zone. 

Supprimer des bordures dans un tableau 

II ressort des explications precedentes que, pour supprimer une bordure, il faut 
mettre a True l'indicateur Is . . . Li neVal i d, et mettre les elements InnerLi neWi dth et 
OuterLineWidth de la structure BorderLine correspondante a zero. Un moyen plus 
simple est ce codage : 

Dim bordures As New com. sun. star. table. TableBorder 
bordures . IsTopLi neVal i d = True 
bordures. IsVerticalLineValid = True 
maZone.TableBorder = bordures 
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On cree une structure TableBorder vierge, avec tous ses elements a zero, et on met a 
True les indicateurs de validite des lignes a effacer, ici la ligne du haut et les lignes 
interieures verticales. 



Cellules fusionnees 

Lorsqu'une zone de cellules est fusionnee, la cellule du coin haut-gauche de la zone 
voit sa pseudo-propriete IsMerged (en fait la methode getlsMerged) prendre la 
valeur True. Pour les autres cellules de la zone, cette meme propriete prend la valeur 
False. La methode merge(True) fusionne les cellules d'une zone ; inversement pour 
scinder la zone afin de retrouver les cellules d'origine, on emploie la methode 
merge(Fal se) de la cellule du coin haut-gauche de la zone. Cet exemple fusionne ou 
scinde une zone de cellules. 

rem Code09-02 .ods bibli : Fusionner Modulel 
Option Explicit 

Sub Fusi onner_Sci nder_Zone() 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 
Dim maZone As Object, celluleCoin As Object 
monDocument = thi sComponent 
lesFeuilles = monDocument. Sheets 
maFeuille = 1 esFeui 1 1 es . getByName("Feui 11 e2") 
" celluleCoin = maFeuille. getCel 1 RangeByName("B21") 
if cell ul eCoi n . IsMerged then 

celluleCoin.merge(False) ' scinder la zone fusionnee 
el se 

maZone = maFeuille. getCellRangeByName("B21:D22") 

maZone . merge (True) ' fusionner la zone 
end if 
End Sub 

Notez que dans une zone fusionnee vous pouvez toujours acceder aux cellules initiales 
avec l'API. Sachant qu'une cellule appartient a une zone fusionnee, comment trouver 
les coordonnees de cette zone ? Pour cela nous devons utiliser un curseur de cellule. Cet 
objet possede les proprietes d'une cellule ou d'une zone de cellules, selon qu'il est ponc- 
tuel ou etale. On l'obtient avec la methode createCursor ou la methode 
createCursorBy Range. Nous emploierons cette derniere pour obtenir un curseur poin- 
tant sur la cellule du coin de la zone. La methode collapseToMergedArea du curseur 
sert a l'etaler sur la zone fusionnee. On peut alors obtenir l'equivalent d'un objet zone 
de cellules dont nous avons vu comment recuperer l'adresse ou les coordonnees. 

rem Code09-02 .ods bibli : Fusionner Module2 
Option Explicit 
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Sub RetrouverZoneFusionneeO 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 

Dim maCellule As Object, curseurCellule As Object 

monDocument = thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = lesFeuilles.getByName("Feuille2") 

maCellule = maFeui 1 1 e . getCel 1 RangeByName("C22") 

curseurCellule = maFeui 11 e . createCursorByRange(maCell ul e) 

cu rseu rCel 1 ul e . col 1 apseToMergedArea 

MsgBox("Cellule : " & maCellule.AbsoluteName & chr(13) & _ 

"Zone fusionnee : " & curseurCellule. Absol uteName) 
End Sub 

La propriete Absol uteName nous permet d'afficher facilement les coordonnees de la 
zone fusionnee, ainsi que celles de la cellule. Si la cellule nest pas dans une zone 
fusionnee, les adresses obtenues sont identiques : l'adresse de la cellule. La propriete 
RangeAddress du curseur de cellules est plus pratique pour connaitre les coordonnees 
de la zone par programme. 



Lignes et colonnes 

Une zone de cellules delimite un ensemble de lignes et un ensemble de colonnes qui 
traversent la zone, cette derniere pouvant se reduire a une seule cellule. Une ligne ou 
une colonne est assimilee par l'API a une zone de cellules, et supporte done les 
memes proprietes. Rappelons aussi qu'une feuille est aussi une zone de cellules cou- 
vrant toute la feuille. Les possibilites sont identiques pour les lignes et les colonnes, 
comme nous allons le voir. 

Les lignes 

A partir d'une zone de cellules, on obtient un objet contenant les lignes grace a la 
propriete Rows de l'objet zone. On accede a chacune des lignes depuis cet objet Rows, 
soit avec la methode getBylndex, soit en Basic par indexation directe ; l'index zero 
correspond a la premiere ligne de la zone. 

Dim lesLignes As Object, uneLigne As Object 

maZone = uneFeui 11 e . getCel 1 RangeByName("E3 : 17") 
lesLignes = maZone.Rows 

print "Nombre de lignes : " & lesLignes. Count 
uneLigne = lesLignes(l) ' deuxieme ligne de la zone 
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Les proprietes listees dans le tableau 9-13 sont disponibles aussi bien pour une ligne 
que pour une collection de lignes. Elles peuvent etre lues et modifiees. 



Tableau 9-13 Proprietes de lignes 



Propriete Type Signification 


IsVisible 


Boolean 


True si la ligne est visible, 
Fal se si elle est cachee. 


Height 


Long 


Hauteur de la ligne en 1/1 00 de mm. 


Optimal Height 


Boolean 


True : la ligne adapte sa hauteur a son contenu. 
Fal se : la hauteur depend de la propriete Hei ght. 



La methode i nsertBylndex de l'objet collection de lignes ajoute plusieurs lignes. 
Dans cet exemple, on ajoute trois lignes groupees dont la premiere aura le rang 1 
dans la collection : 



lesLignes.insertByIndex(l, 3) 

La methode removeBylndex de l'objet collection de lignes supprime plusieurs lignes. 
Dans cet exemple, on supprime trois lignes groupees dont la premiere aura le rang 1 
dans la collection : 

lesLignes. removeByIndex(l, 3) 



Les colonnes 

A partir d'une zone de cellules, on obtient un objet contenant les colonnes grace a la 
propriete Col umns de l'objet zone. On accede a chacune des colonnes depuis cet objet 
Columns, soit avec la methode getBylndex, soit en Basic par indexation directe ; 
l'index zero correspond a la premiere ligne de la zone. 

Dim lesCols As Object, uneCol As Object 

maZone = uneFeuille.getCellRangeByName("E3:37") 
lesCols = maZone. Col umns 

I print "Nombre de colonnes : " & lesCols. Count 
uneCol = lesCols(l) ' deuxieme colonne de la zone 

Les proprietes listees dans le tableau 9-14 sont disponibles aussi bien pour une 
colonne que pour une collection de colonnes. Elles peuvent etre lues et modifiees. 
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Tableau 9-14 Proprietes de colonnes 



IsVisible 


Boolean 


True si la colonne est visible, 
Fal se si elle est cachee. 


Width 


Long 


Largeur de la colonne en 1/100 de mm. 


Optimal Width 


Boolean 


True : la colonne adapte sa largeur a son contenu. 
Fal se : la largeur depend de la propriete Wi dth. 



La methode insertBylndex de l'objet collection de colonnes ajoute plusieurs 
colonnes. Dans cet exemple, on ajoute trois colonnes groupees dont la premiere aura 
le rang 1 dans la collection : 

1 esCol s . i nsertBy Index (1, 3) 

La methode removeBylndex de l'objet collection de colonnes supprime plusieurs 
colonnes. Dans cet exemple, on supprime trois colonnes groupees dont la premiere 
aura le rang 1 dans la collection : 

lesCol s . removeBylndex (1, 3) 



Lire et ecrire dans une cellule 

Les differents contenus d'une cellule 

Le contenu d'une cellule se presente sous une des quatre formes suivantes : 

• cellule vide ; 

• valeur numerique (un nombre) ; 

• un texte (qui peut etre tres long) ; 

• une formule (qui s'evalue comme une valeur numerique ou un texte). 

Les proprietes du tableau 9-15 permettent de connaitre ou modifier le contenu d'une 
cellule. 



Tableau 9-15 Proprietes liees au contenu de la cellule 



Propriete 






Type 


Long 


Lecture seulement. 

Type de contenu de la cellule ; constante nommee, voir texte. 


Stri ng 


Stri ng 


Texte affiche par la cellule. 
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Tableau 9-15 Proprietes liees au contenu de la cellule (suite) 



Value 


Double 


Valeur numerique de la cellule. 


Formula 


String 


Formule de la cellule, exprimee en anglais US. 


FormulaLocal 


String 


Formule de la cellule, exprimee dans la langue de I'interface 
utilisateur. 



La propriete Type fournit le type de contenu de la cellule sous forme d'une constante 
nommee de la forme : 



com . sun . star . tabl e . Cel 1 ContentType . TEXT 

Vous trouverez la liste complete de ces constantes dans le prochain exemple. Pour 
« vider » le contenu d'une cellule, il suffit de mettre une chaine vide dans sa propriete 
Stri ng : 

maCellule. String = "" 

La propriete Stri ng de la cellule fournit le texte affiche par celle-ci. Pour une valeur 
numerique, ce texte tient compte du format du nombre, par exemple le nombre de 
decimales. 

Quand la cellule contient un nombre ou une formule qui s'evalue en nombre, sa pro- 
priete Value renvoie la valeur ; cette propriete est du type Double, meme si visuelle- 
ment la cellule affiche un nombre entier ou une date ; si vous mettez dans Val ue une 
valeur d'un autre type, elle sera convertie en Double avant le stockage effectif 

Quand la cellule contient une formule (c'est-a-dire que son contenu debute par le 
signe =), la propriete Formul aLocal renvoie l'expression dans la langue de I'interface uti- 
lisateur. Si la formule renvoie un texte, la propriete Val ue contient zero meme si le texte 
obtenu est celui d'un nombre. Si la formule renvoie une valeur numerique, la propriete 
String contient un texte representant la valeur. La propriete Formula renvoie l'expres- 
sion en langue anglaise US, les fonctions utilisent leur nom interne, parfois complexe. 

Pour bien comprendre ces proprietes, le mieux est de les afficher pour divers con- 
tenus de cellule. Cliquez sur une cellule de tableur et executez la macro ci-apres. Le 
fichier du Zip telechargeable contenant la macro comporte des cellules interessantes 
sur la feuille Contenus. 

rem Code09-01.ods bibli : UneCellule Modulel 
Option Explicit 



Les documents Calc 

Chapitre 9 



Sub ContenuDeCelluleO ' pointez une cellule sur une feuille 

Dim monDocument As Object, maCellule As Object 

Dim mess As String, cr As String 

cr = chr(13) ' retour a la ligne 

monDocument = Thi sComponent 

maCellule = monDocument. currentSelection 

if maCellule. supportsService("com. sun. star. table. Cell") then 
Select Case maCellule. Type 

Case com . sun . star . tabl e . Cel 1 ContentType . EMPTY 

mess = "La cellule est vide" 
Case com . sun . star . tabl e . Cel 1 ContentType . TEXT 

mess = "La cellule contient du texte" 
Case com . sun . star . tabl e . Cel 1 ContentType . VALUE 

mess = "La cellule contient une valeur" 
Case com . sun . star . tabl e . Cel 1 ContentType . FORMULA 
mess = "La cellule contient une formule" 
if maCellule. Value = 0 then 

if maCell ul e . String <> "0" then 

mess = "La cellule contient une formule donnant un texte" 
el se 

mess = "La cellule contient une formule donnant zero" 
end if 
el se 

mess = "La cellule contient une formule donnant une valeur" 
end if 
End Select 

MsgBox mess & cr & "String : " & maCellule. String & cr & 
"Value : " & maCellule. Value & cr & _ 
"Formula : " & maCellule. Formula & cr & 
"FormulaLocal : " & maCel 1 ul e . Formul aLocal & cr 

el se 

MsgBox("Une seule cellule SVP !", 16) 
end if 
End Sub 

Les proprietes de cellule qui permettent de connaitre le contenu sont aussi utilisables 
pour remplir une cellule. Une seule de ces instructions suffit, la propriete Type sera 
mise a jour automatiquement : 

maCellule. String = "Un petit texte" 
maCellule. Value = 12345 
maCellule. Formul a = "=ROUND(F37/3 . 14) " 
maCellule. Formul aLocal = "=ARRONDI(F37/3 , 14) " 

Remarquez les exemples utilisant Formula et FormulaLocal : dans le premier, le 
nombre est ecrit a l'anglaise (point decimal), dans le deuxieme il est ecrit selon les 
regies propres a la langue de l'interface utilisateur, ici avec une virgule decimale. 
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Si, par exemple, vous etes sur que la langue de l'interface utilisateur est le francais, 
utilisez la propriete Formul aLocal , cela vous permettra d'ecrire les formules plus sim- 
plement. Au contraire, si vous n'etes pas sur de la langue de l'interface utilisateur 
(contexte d'entreprise multinationale) a 1' execution de la macro, utilisez Formula. La 
feuille NomsFonctions du document Code09-01.ods liste les correspondances des 
noms de fonctions. 



Le curseur d'ecriture dans la cellule 

Si vous savez comment ecrire du texte par macro dans un document Writer, vous 
retrouverez ici les memes concepts, mais pas toutes les possibilites. 

Nous venons de voir la methode la plus simple pour lire ou ecrire un texte dans une 
cellule : utiliser sa propriete Stri ng. Pour avoir plus de possibilites, il faut utiliser un 
curseur d'ecriture, qui pointe sur un endroit dans le texte de la cellule : le point 
d'insertion. On obtient un curseur d'ecriture a partir de l'objet cellule : 

Dim monCurseur As Object 

monCurseur = maCellule. createTextCursor 

A sa creation, le curseur d'ecriture pointe a la fin du texte contenu dans la cellule. 

Deplacer le curseur d'ecriture 

L'objet curseur dispose de plusieurs methodes permettant de le deplacer. Certaines 
renvoient un resultat : 

• True si Taction a pu etre realisee ; 

• Fal se dans le cas contraire. 

En pratique, on utilise rarement le resultat de ces fonctions et on les utilise comme 
des methodes de type Sub. 

Les fonctions de deplacement ont toutes un argument booleen, que nous designe- 
rons par SEL, qui a l'effet suivant : 

• SEL = False : le curseur se deplace (comme la barre verticale du curseur visible 
quand vous editez le texte d'une cellule). 

• SEL = True : le curseur se deplace en etendant la selection (c'est le meme effet 
qu'une selection progressive du curseur visible en faisant glisser la souris). 

Et voici un petit exemple : 
Dim monDocument As Object 

Dim lesFeuilles As Object, maFeuille As Object 
Dim maCellule As Object, monCurseur As Object 
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monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 11 es . getByName("Ecri re") 

maCellule = maFeui 1 1 e . getCel 1 RangeByName("C2") 

monCurseur = maCellule.createTextCursor 

' ici le curseur est a la fin du texte 

monCurseur . gotoStart(Fal se) 

' ici le curseur est au debut du texte 

Le tableau 9-16 liste les fonctions de emplacement de curseur. 



Tableau 9-16 Deplacement du curseur d'ecriture 







goRight(n.SEL) 


Deplacer de n caracteres a droite. Renvoie True si Taction a ete realisee. 


gol_eft(n,SEL) 


Deplacer de n caracteres a gauche. Renvoie True si Taction a ete realisee. 


gotoStart(SEL) 


Deplacer au debut du texte de la cellule. 


gotoEnd(SEL) 


Deplacer a la fin du texte de la cellule. 



Nous avons signale que le curseur d'ecriture peut selectionner une zone. Apres avoir 
effectue une action sur cette zone, on dispose de deux methodes du curseur pour le 
ramener a un point d'insertion, situe au debut ou bien a la fin de la zone. 

monCurseur. coll apseToStart ' debut de zone 
monCurseur. collapseToEnd ' fin de zone 

L'objet curseur de cellule fournit aussi une fonction booleenne i sCol 1 apsed, qui ren- 
voie Fal se si le curseur est etendu pour une selection et True s'il est ponctuel. 

if monCurseur. isCollapsed then 
' ici le curseur est ponctuel 
end if 



Creer un curseur a partir d'un autre curseur 

Dans certains cas, il est interessant d'utiliser un autre curseur d'ecriture qui soit ini- 
tialise aux valeurs du curseur actuel. On utilise pour cela la methode 
createTextCursorByRangede l'objet Text. Dans cet exemple, curseur2 reprend la 
position et la selection dans le texte memorisees par curseurl : 

Dim monDocument As Object 

Dim lesFeuilles As Object, maFeuille As Object 
Dim maCellule As Object 

Dim curseurl As Object, curseur2 As Object 
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I monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
maFeuille = 1 esFeui 1 1 es . getByName("Ecri re") 
maCellule = maFeuille. getCellRangeByName("C2") 
curseurl = maCell ul e . createTextCursor 
curseur2 = maCellule.createTextCursorByRange(curseurl) 
' curseur2 est a la fin du texte 
curseurl.gotoStart (False) 
' curseurl est au debut du texte 

Les objets curseurl et curseur2 peuvent etre deplaces ou modifies independam- 
ment Fun de l'autre. 

Si le premier curseur selectionne une zone, le deuxieme curseur peut etre cree a partir 
du premier en precisant qu'il doit se positionner a la fin de la zone de texte 
selectionnee : 

curseur2 = maCel 1 ul e . createTextCursorByRange(curseurl. End) 

Pour le positionner au debut de la zone selectionnee, on ecrirait : 
curseur2 = maCellule.createTextCursorByRange(curseurl. Start) 

En fait, il est possible de definir un curseur a partir d'un objet zone de texte 
(TextRange). Cet objet designe une partie de texte, mais il ne possede pas les 
methodes d'un objet curseur. 

Lire un texte dans une cellule 

Nous savons recuperer le texte entier contenu dans une cellule. En utilisant le depla- 
cement du curseur d'ecriture, nous allons recuperer une partie du texte. 

rem Code09-01.ods bibli : UneCellule Module2 

Option Explicit 

Sub Li reUnMorceau() 

Dim monDocument As Object 

Dim lesFeuilles As Object, maFeuille As Object 

Dim maCellule As Object, monCurseur As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Ecri re") 

maCellule = maFeuille. getCell RangeByName("C2") 

monCurseur = maCell ul e . createTextCursor 

monCurseur .goLeft(4, true) 

print monCurseur. String 

End Sub 
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La macro cree un curseur dans une cellule ; il se situe alors en fin de texte. Le depla- 
cement a gauche selectionne les quatre caracteres precedents. La macro affiche 
ensuite le contenu de la propriete String (de type String) de l'objet curseur (ne pas 
confondre avec la propriete Stri ng de l'objet cellule). 



Inserer un texte dans une cellule 

Ici, nous allons inserer un texte dans un texte existant. La premiere methode consiste 
a utiliser la propriete Stri ng du curseur. En reprenant l'exemple precedent, ajouter la 
ligne suivante remplacera le texte selectionne par un nouveau texte : 

monCurseur. String = "Terre" 

Si le curseur etait ponctuel, le texte serait insere au point d'insertion. Cependant, 
pour ajouter un autre texte a la suite, vous devez deplacer le curseur. La deuxieme 
methode effectue un deplacement automatique du curseur. 

maCellule.insertString(monCurseur, "blabla", SEL) 

La methode insertString de l'objet cellule utilise trois arguments. Le premier est 
un objet curseur d'ecriture ; le deuxieme est la chaine de caracteres a inserer. 

Le troisieme argument recoit en general la valeur Fal se. La valeur True est employee 
pour remplacer une zone prealablement selectionnee avec le curseur. Le curseur rede- 
vient ponctuel et se positionne a droite du texte ajoute. Un nouvel appel de la methode 
ajoutera du texte dans le sens d'ecriture. L'exemple suivant suppose une cellule conte- 
nant le texte « Un navire », que la macro va transformer en « II etait un petit navire ». 

rem Code09-01 . ods bibli : UneCellule Module3 
Option Explicit 

Sub InsererTexteO 

Dim monDocument As Object , txl As String 
Dim lesFeuilles As Object, maFeuille As Object 
Dim maCellule As Object, monCurseur As Object 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
maFeuille = 1 esFeui 11 es . getByName("Ecri re") 
maCellule = maFeui 1 1 e . getCel 1 RangeByName("C5") 
monCurseur = maCell ul e . createTextCursor 
monCu rseu r . gotoStart (fal se) 

monCurseur. goRight(2, true)' selectionner "Un" 
txl = "II etait un" 
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maCellule. insertStringCmonCurseur, txl, true) 
maCellule. insertStringCmonCurseur, " petit", false) 

End Sub 

Inserer des caracteres speciaux 

La methode i nsertControlCharacter de l'objet cellule permet d'inserer une marque 
de paragraphe. L'exemple suivant utilise une cellule contenant deja un texte et ajoute 
un nouveau paragraphe suivi d'un texte. 

rem Code09-01.ods bibli : UneCellule Module4 
Option Explicit 

Sub InsererParagraphe() 
Dim monDocument As Object 

Dim lesFeuilles As Object, maFeuille As Object 
Dim maCellule As Object, monCurseur As Object 
Dim special As Integer 

special = com. sun. star. text. Control Character. PARAGRAPH BREAK 

monDocument = Thi sComponent 

lesFeuilles = monDocument. Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Ecri re") 

maCellule = maFeui 11 e . getCell RangeByName("C2") 

monCurseur = maCellule. createTextCursor 

maCellule. insertControlCharacter(monCurseur, special, false) 

maCellule. insertStringCmonCurseur, "Mon ami Pierrot", false) 
End Sub 

Le premier argument de i nsertControlCharacter est un objet curseur. 

Le deuxieme argument est une valeur numerique du type Integer, qui se definit par 
une constante nommee. Deux valeurs seulement sont utilisables : 

com . sun . star . text . Control Character . PARAGRAPH BREAK 
com . sun . star . text . Control Characte r . APPEND PARAGRAPH 

Avec la premiere valeur, la marque de paragraphe est inseree a la position du curseur. 
Avec la deuxieme valeur, la marque de paragraphe est inseree a la fin du paragraphe 
dans lequel se trouve le curseur, puis le curseur est positionne au debut de ce nouveau 
paragraphe. 

Formatage de certains caracteres 

Les proprietes de formatage sur l'ensemble de la cellule sont aussi disponibles sur un 
curseur d'ecriture. Ceci nous permet d'effectuer un formatage sur une zone du texte 
de la cellule. Dans l'exemple qui suit nous allons imposer un formatage sur 
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l'ensemble du texte d'une cellule, puis imposer un formatage sur trois caracteres du 
texte d'une autre cellule. 

rem Code09-02 . ods bibli : Formater Module4 
Option Explicit 

Sub FormaterCaractereO 

Dim monDocument As Object, lesFeuilles As Object 
Dim maFeuille As Object, maCellule As Object 
Dim monCurseur As Object 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
maFeuille = lesFeuilles. getByName("Feuille2") 
maCellule = maFeui 11 e . getCell RangeByName("B13") 
With maCellule 
.CharHeight = 14 

.CharColor = RGB (0 , 100 , 100) ' couleur bleu-vert 
.CharUnderl i ne = com . sun . star . awt . FontUnderl i ne . DASHD0T 
End With 

maCellule = maFeui 11 e . getCell RangeByName("D15") 
monCurseur = maCell ul e . createTextCursor ' positionne a la fin 
monCurseur. goLeft(3 , true) ' selectionner les 3 derniers car. 
monCurseur. CharColor = RGB(200,0,0) ' les peindre en rouge 
End Sub 



Methodes applicables a une zone de cellules 

Les principes que nous allons decrire sont aussi valables pour une zone de cellules 
selectionnee par l'utilisateur et pour une feuille Calc, car cette derniere possede les 
fonctionnalites d'une zone de cellules couvrant toute la feuille. 

Effacer une zone de cellules 

La methode clearContents d'un objet zone de cellules est tres pratique pour reini- 
tialiser toute une zone selon certains criteres, qui sont specifies avec des constantes 
nominees de la forme : 

com . sun . star . sheet . Cel 1 Fl ags . STRING 

Ces constantes sont listees au tableau 9-17. On peut combiner plusieurs criteres en 
les additionnant : le resultat est equivalent a utiliser clearContents avec la premiere 
constante, puis la deuxieme, etc. 
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Tableau 9-17 Criteres de choix des cellules 



Constante Signification 


VALUE 


Cellules ayant un contenu numerique , sauf les contenus au format de date ou heure. 


DATETIME 


Cellules ayant un contenu numerique au format de date ou heure. 


STRING 


Cellules ayant un contenu de texte. 


ANNOTATION 


Cellules contenant une note. 


FORMULA 


Cellules contenant une formule (pas une simple valeur numerique). 


HARDATTR 


Cellules ayant un formatage specifique (autre que celui du style de la cellule). 


STYLES 


(fonctionnement actuellement identique a HARDATTR) 


OBJECTS 


Cellules contenant un objet de dessin (le dessin doit etre entierement dans la zone analysee). 


EDITATTR 


Cellules comportant un formatage sur une partie du texte. 



A titre d'exemple, nous allons effacer le formatage local des cellules et supprimer leur texte. 

rem Code09-03 . ods bibli : Fonctions Module5 
Option Explicit 

Sub Ef facerZoneO 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maZone As Object 

Dim gomme As Long 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Fonctions") 

maZone = maFeui 1 1 e . getCell RangeByName("B30 : D33") 

gomme = com. sun. star. sheet. Cell Flags. HARDATTR + 

com . sun . star . sheet . Cel 1 Fl ags . STRING 
maZone . cl earContents (gomme) 

End Sub 

Cette methode s'applique aussi a une seule cellule. 



Enumerer les cellules d'une zone 

La methode que nous allons exposer est applicable a toute zone de cellules, ainsi qua 
toute selection faite par i'utilisateur. Cet exemple, typique des methodes d'enumera- 
tion, recherche dans la zone toutes les cellules contenant du texte et met ce texte en 
majuscules. 

rem Code09-01.ods bibli : ZonesCel 1 ul es Module6 
Option Explicit 
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Sub CellulesMajusculesO 

Dim controleur As Object, maFeuille As Object 

Dim sel As Object, listeCell As Object, selectionCell As Object 

Dim uneCellule As Object, enumCellules As Object 

controleur = ThisComponent.CurrentController 

maFeuille = controleur. ActiveSheet 

sel = ThisComponent.CurrentSelection 

'sel = maFeuille. getCel 1 RangeByName("NomDeZone") 

'sel = maFeuille. getCell RangeByName("Cll:D12") 

selectionCell = sel . queryContentCel Is (com. sun. star. sheet. Cell Flags. STRING) 
enumCellules = selectionCell .Cells 
listeCell = enumCel 1 ul es . createEnumeration 
Do While 1 i steCel 1 . hasMoreEl ements 

uneCellule = listeCell .nextElement 

uneCellule. String = UCase(uneCellule. String) 
Loop 
End Sub 

Nous utilisons la methode queryContentCel 1 s de la selection. Cette selection peut etre 
une zone de cellules, eventuellement reduite a une seule cellule, ou un ensemble de zones 
selectionnees par l'utilisateur, comme ici. La methode queryContentCel 1 s utilise les 
memes indicateurs Cell Flags que nous avons vus au tableau 9-15. Ici aussi on peut 
additionner les valeurs pour retenir les cellules correspondant a un ou plusieurs criteres. 

Nous obtenons l'objet selectionCell dont la pseudo-propriete Cells renvoie un 
objet contenant les references des cellules, a partir duquel nous creons un objet per- 
mettant d'obtenir les cellules une a une (l'ordre d'obtention des cellules ne peut etre 
predit). II ne nous reste plus qua effectuer le traitement sur chaque cellule. 

Le meme principe pourrait, par exemple, rechercher et traiter toutes les cellules non 
vides d'une zone. 



Trouver les cellules utilisees 

Dans une feuille Calc, on a une table avec une ou plusieurs lignes d'en-tetes et un nombre 
inconnu de lignes de resultats. Comment connaitre l'etendue de la zone de resultats ? 

Dim fResu As Object, zoneResu As Object, curseurCell As Object 
fResu = Thi sComponent . Sheets . getByName("Resul tats") 

curseurCel 1 = fResu . createCursorByRange (fResu . getCel 1 RangeByName("A2")) 
curseurCel 1 . gotoEndOfUsedArea(True) 

zoneResu = fResu . getCel 1 rangeByName(curseurCell . Absol uteName) 
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if zoneResu . RangeAddress . StartRow >= 1 then 

1 ici effectuer un traitement sur la zone de resultats 
end "if 

On utilise pour cela un curseur de cellule, initialise a la position de debut des resul- 
tats, ici A2 car l'en-tete comporte seulement la ligne 1. La methode 
gotoEndOfUsedArea avec un argument True va etendre le curseur de cellule sur 
l'ensemble des cellules utilisees a partir de la position de depart. La propriete 
Absol uteName du curseur de cellule donne l'adresse textuelle de la zone obtenue, ce 
qui nous permet d'obtenir un objet zone de cellules couvrant la zone des resultats. 

Mais il existe un cas particulier : s'il n'y a aucun resultat, la zone obtenue est 
incorrecte ! Elle debute a la ligne precedente, qui contient l'en-tete. Aussi devons- 
nous tester si la premiere ligne de la zone (StartRow) est bien au-dela de l'en-tete. 
Dans ce cas seulement, nous avons des resultats que nous pouvons analyser avec la 
zone de cellules obtenue. 



Piece Les cellules apparemment utilisees 

La methode gotoEndOfUsedArea considere comme utilisee toute cellule comportant une valeur ou 
un texte ou une formule ou un formatage local (couleur, bordure...). Une feuille avec des restes d'ancien- 
nes manipulations peut donner une zone trop grande (cellules inutilisees tres a droite ou bien plus bas 
que la zone). Done veillez a la « proprete » de la feuille. Si vous souhaitez un formatage particulier pour 
les resultats, utilisez des styles de cellules dans cette zone car la methode n'en tient pas compte. 



Trouver les cellules vides 

Une feuille Calc contient une table avec plusieurs colonnes. On ne connait pas exac- 
tement le nombre de lignes utiles, mais on sait a quelle ligne se trouve l'en-tete de la 
table, et on sait egalement qu'une colonne particuliere contient toujours des cellules 
non vides, jusqu'a la fin des donnees de la table. Dans la meme feuille, on a d'autres 
informations, en dehors de la zone de la table. 

Ce codage trouve le rang de ligne correspondant a la premiere cellule vide dans la colonne, 
ce qui permet d'en deduire le nombre de lignes de la table. Ici on utilise la colonne A, l'en- 
tete est en ligne 1, la table peut s'etendre au maximum jusqu'a la ligne 100. 

Dim zonesVides As Variant 

maZone = maFeui 1 1 e . getCell RangeByName("A2 : A100") 
zonesVides = maZone.queryEmptyCells.RangeAddresses 

if UBound(zonesVides) < 0 then 

print "aucune zone vide dans la zone" 
el se 

' la premiere zone memorisee correspond au balayage de haut en bas 
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y = zonesVi des (0) . StartRow 
print "Vide a parti r de la ligne " & y+1 
end if 

La methode queryEmptyCel 1 s de la zone de cellules (ici une colonne) recherche les 
cellules vides et renvoie un objet dont nous utilisons la pseudo-propriete 
RangeAddresses. Celle-ci renvoie un tableau de structures Cell RangeAddress. Nous 
avons vu cette structure dans l'introduction aux zones de cellules. Si l'index maximal 
est negatif, il n'y a aucune cellule vide ; sinon, la premiere zone de cellules vides ren- 
contree est a l'index zero. Lelement StartRow de la structure nous renseigne sur la 
ligne de debut de cette zone. 

On pourrait enumerer les cellules vides en utilisant la pseudo-propriete Cel 1 s de la 
methode queryEmptyCel! s, comme nous l'avons montre plus haut avec la methode 
queryContentCell s. 

Le meme principe fonctionne en horizontal pour trouver la premiere cellule vide sur une 
zone correspondant a une ligne. Si la zone est un rectangle, on constate que le resultat 
correspond a un balayage par colonnes, depuis la gauche vers la droite, puis par lignes. 



La methode queryEmptyCel 1 s ne considere que les cellules ne contenant ni valeur, ni texte, ni for- 
mule. Elle est indifferente au formatage des cellules. 



Formule matricielle 

Pour appliquer une formule matricielle sur une zone de cellules, on doit utiliser la 
pseudo-propriete ArrayFormula de cette zone (ne pas confondre avec Formul aArray). 
Pour calculer ligne a ligne sur les cellules CI a G5 une expression utilisant les valeurs 
des cellules Al a A5 et Bl a B5, on ecrira ce genre de formule : 

Dim maFeuille As Object, maZone As Object 

maZone = maFeuille. getCellRangeByName("Cl:C5") 
maZone. ArrayFormula = "=SQRT(A1:A5*A1:A5+B1:B5*B1:B5)" 

La formule est ecrite sous forme de chaine de caracteres, sans les accolades que vous 
verrez sur le tableur. Si, comme dans cet exemple, vous utilisez une fonction de Calc, 
celle-ci doit etre ecrite avec son nom en version anglaise. La feuille NomsFonctions 
du document Code09-01.ods liste les correspondances de noms de fonctions. Bizar- 
rement, si vous affichez le contenu de la pseudo-propriete ArrayFormula, vous 
obtiendrez une formule localisee ! 
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Pour chaque cellule de la formule matricielle, la pseudo-propriete Formula contient 
la formule anglaise avec accolades, et la propriete FormulaLocal contient la formule 
localises, avec accolades. 

Fonctions mathematiques sur une zone de cellules 

L'API OpenOffice.org offre une serie de fonctions courantes qui s'appliquent a une zone 
de cellules et renvoient un resultat numerique de type Double. II suffit d'utiliser la 
methode computeFuncti on de l'objet zone de cellules, en donnant en argument une cons- 
tants nommee (tableau 9-18) qui precise la fonction. Ces constantes sont de la forme : 

com. sun .star. sheet. General Function. MAX 

Tableau 9-18 Fonctions mathematiques de zone de cellules 



NONE 


Aucun calcul n'est effectue. 


AUTO 


Si tous les contenus sont numeriques la fonction SUM est appliquee, sinon la fonc- 
tion COUNT est appliquee. 


SUM 


Somme de tous les contenus numeriques. 


COUNT 


Le nombre de tous les contenus, numeriques ou non. 


AVERAGE 


Moyenne de tous les contenus numeriques. 


MAX 


Valeur maximale de tous les contenus numeriques. 


MIN 


Valeur minimale de tous les contenus numeriques. 


PRODUCT 


Produit de tous les contenus numeriques. 


COUNTNUMS 


Nombre des contenus numeriques. 


STDEV 


Deviation standard basee sur un echantillon. 


STDEVP 


Deviation standard basee sur la population entiere 


VAR 


Variance calculee sur un echantillon. 


VARP 


Variance calculees sur la population entiere. 



L'utilisation est tres simple : 

rem Code09-03 . ods bibli 
Option Explicit 
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Sub FonctionAPIdeZoneO 

Dim monDocument As Object, lesFeuilles As Object 
Dim maFeuille As Object, maZone As Object 
Dim fonc As Integer, resu As Double 
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monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 11 es . getByName("Foncti ons") 

maZone = maFeuille. getCellRangeByName("Bll:C13") 

fonc = com. sun. star .sheet. General Function. MAX 
resu = maZone.computeFunction(fonc) 

print "Resultat : " & resu 
End Sub 

Cette methode s' applique aussi a une seule cellule. 



Lire et ecrire les donnees d'un tableau 

II est assez penible de lire et ecrire dans plusieurs cellules successivement. Or dans 
bien des cas, on doit effectuer des traitements sur toutes les cellules d'une zone. 

La propriete DataArray de l'objet zone de cellules permettent de copier les valeurs de 
la zone vers une variable tableau de Basic, afin d'effectuer divers traitements, puis de 
recopier les valeurs du tableau vers la zone de cellules. 

Comme exemple, nous allons supposer que la feuille 2 contient en colonnes B et C 
des nombres representant des annees. Pour des raisons historiques, les annees du 
XX e siecle ont d'abord ete ecrites avec deux chiffres, puis on est passe a quatre chif- 
fres quand on s'est approche de Fan 2000, ce qui fait un tableau incoherent (imaginez 
le probleme avec plusieurs centaines de lignes). Nous allons convertir les dates a deux 
chiffres en dates du XX e siecle. La macro va utiliser les particularites des variables de 
type Variant (revoir dans le chapitre 3 les tableaux de tableaux). De plus, l'utilisation 
de Vari ant nous donne une solution plus generale car elle pourrait traiter des cellules 
contenant du texte. 

rem Code09-03 . ods bibli : Calculs Modulel 
Option Explicit 

Sub Converti rAnnees2chi f f res () 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 

Dim maZone As Object, lesAns As Variant, uneLigne As Variant 

Dim ligne As Long, colonne As Long 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 11 es . getByName("Feui 11 e2") 

maZone = maFeui 1 1 e . getCel 1 RangeByName("B2 : Cll") 

lesAns = maZone. DataArray 

for ligne = LBound(l esAns) to UBound(lesAns) 
uneLigne = 1 esAns(l igne) 
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for colonne = LBound(uneLigne) to UBound(uneLigne) 

"if uneLigne(colonne) < 100 then 

uneLigne(colonne) = uneLigne(colonne) +1900 
end if 
next colonne 

lesAns(l igne) = uneLigne 

next "I igne 

maZone.DataArray = lesAns 

End Sub 

La variable TesAns re9oit les valeurs des cellules de la zone B2 a Cll. Elle est ainsi 
transformee par 1' affectation en un tableau a une dimension dont l'index est le 
numero de ligne dans la zone de cellules. Le contenu de chaque element du tableau 
Basic est aussi un tableau a une dimension dont l'index est le numero de colonne 
dans la zone de cellules. Autrement dit, la variable 1 esAns est un tableau de tableaux, 
ce qui est different d'un simple tableau a deux dimensions. Pour explorer la variable, 
nous utilisons deux index pour lesquels les fonctions LBound et UBound donnent les 
valeurs extremes, et une variable intermediaire pour lire et modifier chaque element 
du tableau principal. 



La macro ne modifie pas les cellules vides car dans ces cas, la comparaison a la valeur 100 est evaluee a 
Fal se... ce qui nous arrange bien ! 



Cette structure a deux boucles imbriquees fonctionne aussi pour une zone reduite a une 
seule ligne ou une seule colonne. Lemploi de la nouvelle syntaxe d'acces direct dans un 
tableau de tableaux (voir le chapitre 3) ne simplifierait pas beaucoup le codage. 

Recopier uniquement les valeurs et non le format 

Le but est de recopier les valeurs d'une zone vers une autre, les zones pouvant, 
comme ici, etre situees sur des feuilles differentes d'un meme document Calc. On 
utilisera de nouveau la propriete DataArray. La macro ci-apres fonctionne aussi bien 
pour des valeurs numeriques que texte. Si une cellule source contient une formule, la 
valeur calculee de la formule est recopiee. 

Dim lesFeuilles As Object, zone_src As Object, zone_dest As Object 
lesFeuilles = Thi sComponent . Sheets 

zone_src = 1 esFeui "IT es(l) .getCel 1 RangeByName("C3 : D4") 
zone_dest = 1 esFeui "11 es (0) .getCellRangeByName("F10:Gll") 
zone dest. DataArray = zone src. DataArray 
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Deplacer ou recopier des cellules avec references 

De maniere similaire, la propriete FormulaArray permet de transferer les formules 
d'une zone vers un tableau de tableaux et inversement, ce qui nous permet de recopier 
les formules. Attention, cette recopie ne modifiera pas les references des formules ! 

zoneCible. FormulaArray = zoneSource . FormulaArray 

Le principal interet d'un tableur est sa faculte a deplacer ou recopier intelligemment 
des cellules contenant des references a d'autres cellules. Par exemple, si vous deplacez 
une cellule referencee par une autre, la formule de la deuxieme cellule sera modifiee 
automatiquement pour pointer sur le nouvel emplacement de la premiere. Si vous 
copiez la deuxieme a un autre emplacement, la copie pointera sur une cellule ayant la 
meme position relative. Si une reference comporte des caracteres comme $A3 ou A$3 
ou $A$3, le deplacement ou la copie ne modifient pas l'index prefixe par le dollar. 

Attention, les methodes que nous allons voir ne fonctionnent qua l'interieur d'un 
meme document Calc. 



Deplacer une zone de cellules 

L'objet feuille expose la methode moveRange qui utilise deux arguments : 

1 l'adresse de la cellule qui se trouve au coin haut gauche de la zone d'arrivee, 

2 l'adresse de la zone de depart. 

La cellule d'arrivee et la zone de depart peuvent se trouver dans la meme feuille ou 
une feuille differente du meme document Calc. Bizarrement, le deplacement 
s'effectue indifferemment en utilisant la methode moveRange de la feuille de depart, 
de la feuille d'arrivee, ou de toute autre feuille du classeur. 

Dans cet exemple et les suivants, nous utiliserons par convention des noms commen- 
cant par c pour une cellule, z pour une zone, f pour une feuille. 

rem Code09-03 . ods bibli : References Modulel 
Option Explicit 

Sub DeplacerZoneO 

Dim monDocument As Object, lesFeuilles As Object 
Dim fDepart As Object, fArriv As Object 
Dim zDepart As Object, cArriv As Object 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
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fDepart = 1 esFeui 11 es . getByName("Ref s") 

zDepart = fDepart. getCellRangeByName("A2 : B3") 

' les feuilles depart et arrivee peuvent etre differentes 

fArriv = 1 esFeui 1 1 es . getByName("Arri vee") 

cArriv = fArriv. getCell RangeByName("F8") 

fArriv . moveRange(cAr ri v . Cel 1 Address , zDepart . RangeAddress) 

End Sub 

Recopier une zone de cellules 

La recopie s'effectue exactement de la meme maniere que pour un emplacement, a 
l'aide de la methode copyRange, qui utilise les memes arguments que moveRange. 

Nous ne presenterons qu'une partie de l'exemple, que vous pourrez retrouver dans le 
Zip telechargeable : 

rem Code09-03 . ods bibli : References Module2 
Option Explicit 

Sub CopierZoneO 

rem tout est identique jusqu'ici — > 

fArriv . copyRange (cAr ri v . Cel 1 Address , zDepart . RangeAddress) 

End Sub 



Recopier une cellule dans une zone 

Comme vous l'avez remarque, nous ne savons que recopier une zone. Comment 
copier une cellule vers toute une zone, en mettant a jour ses references ? 

Dans un premier exemple, nous souhaitons recopier une cellule vers une zone 
colonne. Nous commencons par copier la cellule dans la premiere cellule de la zone 
destinataire. Dans cette operation, la cellule de depart est assimilee a une zone d'une 
cellule. Puis, nous utilisons la methode fill Auto de la zone destinataire, qui recopie 
intelligemment la premiere cellule sur une colonne, de haut en bas. 

rem Code09-03 . ods bibli : References Module3 
Option Explicit 

Sub Copi erlCel 1 ul eDansZone() 

Dim monDocument As Object, lesFeuilles As Object 
Dim fDepart As Object, fArriv As Object 

Dim cDepart As Object, cArriv As Object, zArriv As Object 
Dim direction As Integer 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
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fDepart = 1 esFeui 11 es . getByName("Ref s") 
cDepart = fDepart . getCell RangeByName("B3") 
' commencer par copier une cellule 
fArriv = lesFeuilles.getByNameC'Arrivee") 
cArriv = fArriv. getCel 1 RangeByName("C2") 

fArri v. copyRange(cArri v.Cell Address , cDepart . RangeAddress) 

' multiplier la cellule a 1'arrivee 

zArriv = fArri v. getCel 1 RangeByName("C2 : C32") 

direction = com. sun. star. sheet. FillDirection. TO BOTTOM 

zArriv.fillAuto(direction, 1) 

End Sub 

Nous aurions pu recopier d'abord la cellule en bas de la zone, et completer de bas en haut : 
direction = com. sun . star . sheet . Fi 11 Di recti on .TO_TOP 

Pour une zone d'arrivee horizontale, f i 1 1 Auto peut completer de gauche a droite : 
direction = com. sun . star . sheet . Fi 1 1 Di recti on .TO_RIGHT 

ou de droite a gauche : 
direction = com. sun . star . sheet . Fi 1 1 Di recti on .TO_LEFT 

Le deuxieme exemple consiste a recopier une zone horizontale en l'etalant sur une 
zone rectangulaire. Le principe est identique et fillAuto recopiera la zone horizon- 
tale, ici en partant du bas. 

rem Code09-03 . ods bibli : References Module4 
Option Explicit 

Sub Copi erZonelDansZone2 () 

Dim monDocument As Object, lesFeuilles As Object 
Dim fDepart As Object, fArriv As Object 

Dim zDepart As Object, cArriv As Object, zArriv As Object 
Dim direction As Integer 
monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 

fDepart = 1 esFeui 11 es . getByName("Ref s") 
zDepart = fDepart. getCell RangeByName("D13 : E13") 

' commencer par copier la zone horizontale 
fArriv = lesFeuilles.getByNameC'Arrivee") 
cArriv = fArriv. getCel 1 RangeByName("C9") 

fArriv . copyRange(cArri v . Cell Address , zDepart . RangeAddress) 
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1 multiplier la zone a l'arrivee, en remontant 
zArriv = fArri v. getCell RangeByName("C3 :D9") 
direction = com . sun . star . sheet . Fi 11 Di recti on .TO_TOP 
zArri v. fi HAuto(di rection, 1) 
End Sub 

La methode f i 11 Auto (et une autre methode, f i 1 1 Se ri es) peut remplir des cellules suc- 
cessives avec une suite de valeurs. Ces possibilites sont inutiles pour nous, car il est bien 
plus simple et plus puissant de creer un tableau Basic et de le remplir avec une boucle, 
puis de le recopier dans la feuille avec la propriete DataArray d'une zone de cellules. 

Recopier une formule dans une zone 

Lorsque nous avons decrit plus haut les zones nominees, nous avons signale qu'elles 
permettent de recopier une formule avec mise a jour de ses references. Si nous vou- 
lons recopier intelligemment une formule qui se trouve dans une cellule vers une 
zone cible, une solution est de definir une zone nommee qui recueille la formule. 

L'exemple qui suit suppose, dans la feuille Refs, une cellule en B23 contenant une 
formule calculee sur d'autres cellules de la colonne. Le but est de recopier cette for- 
mule dans les cellules H33 a J 33. 

rem Code09-03 . ods bibli : References Module5 
Option Explicit 

Sub Recopi erFormul e() 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maCellule As Object 

Dim lesZonesNom As Object, x As Long, cellCible As Object 

Const unNom = "x_001h" ' un nom probablement pas utilise! 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

lesZonesNom = monDocument . NamedRanges 

maFeuille = 1 esFeui 1 1 es . getByName("Ref s") 

maCellule = maFeui 11 e . getCell RangeByName("B23") 

if 1 esZonesNom . hasByName(unNom) then ' verifier quand meme 

MsgBox("Le nom existe de zone existe deja",16) 

exit sub 
end if 

lesZonesNom. addNewByName(unNom, maCellule. Formula, 

maCel 1 ul e . Cel 1 Address , 0) 

for x = 7 to 9 ' colonnes H a J 

cellCible = maFeuille. getCell ByPositionCx, 32) ' ligne 33 
cell Cible. Formula = "=" & unNom ' recopie "i ntell i gente" 

next 

End Sub 
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II est necessaire de trouver un nom de zone qui ne soit pas deja utilise. La formule 
recopiee utilisera ce nom, qu'il faudra garder pour quelle fonctionne. Nous creons la 
zone nommee en prenant pour cellule de reference la cellule contenant la formule 
d'origine. Puis nous recopions la formule dans les cellules cibles. 



Les cellules cibles pourraient se trouver dans une autre feuille, ou meme dans un autre document Calc (la 
zone nommee doit alors etre definie dans le document cible). 



Le code employe a ete choisi pour sa simplicite, au detriment de 1' adaptability . Vous 
remarquerez cependant que cette solution est independante du contenu de la formule. 



Rechercher et remplacer 

Les mecanismes de recherche dans un document Calc utilisent un objet « descripteur de 
recherche » obtenu avec la methode createSearchDescriptor de l'objet zone de cel- 
lules. Ce descripteur comporte plusieurs elements a remplir avant de lancer la recherche 
(voir le tableau 9-19). On y retrouve les options de recherche de l'interface utilisateur. 

Tableau 9-19 Descripteur de recherche 



SearchStri ng 


String 


La chatne de caracteres a rechercher dans la propriete Stri ng des 
cellules. 


SearchBackwards 


Boolean 


True pour faire une recherche a reculons ; par defaut, on recher- 
che dans le sens normal de lecture. 


SearchByRow 


Boolean 


True pour rechercher par lignes. 

Fal se pour rechercher par colonnes (valeur par defaut). 


SearchCaseSensi ti ve 


Boolean 


True pour distinguer les majuscules des minuscules dans la 
recherche ; par defaut il n'y a pas de distinction. 
Quelle que soit la valeur de cette propriete, les caracteres accen- 
tues sont toujours differences des caracteres non accentues. 


SearchWords 


Boolean 


True pour rechercher les cellules ne comportant que la chame de 
recherche, sans autre caractere. 


SearchType 


Integer 


Type de cible de recherche. 

0 : rechercher dans les formules et les cellules de valeur fixe 

1 : rechercher dans les valeurs fixes ou resultant d'une formule 

2 : rechercher dans les notes de cellules 


SearchRegularExpression 


Boolean 


True pour faire une recherche avec la methode des expressions 
regulieres ; par defaut, on recherche une simple egalite de chames. 
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Tableau 9-19 Descripteur de recherche (suite) 



SearchStyl es 


Bool ean 


True pour rechercher des cellules d'un style donne par 
SearchString ; le nom du style est celui affiche par le styliste. 
Par defaut, on cherche un contenu de cellule. 


SearchSi mi 1 ari ty 


Bool ean 


True pour rechercher un texte similaire au texte cherche. 


SearchSi mi 1 ari tyRel ax 


Boolean 


True pour essayer toute combinaison des trois criteres suivants 
qui permette de retrouver le texte cherche. 


SearchSi mi 1 ari tyRemove 


Integer 


Nombre de caracteres a retrancher pour retrouver le texte cherche. 


SearchSi mi 1 ari tyAdd 


Integer 


Nombre de caracteres a ajouter pour retrouver le texte cherche. 


SearchSi mi 1 ari tyExchange 


Integer 


Nombre de caracteres a changer pour retrouver le texte cherche. 



Rechercher toutes les occurrences 

Nous allons utiliser le descripteur de recherche pour trouver toutes les occurrences 
d'un terme dans les cellules texte de la zone. Chaque cellule trouvee est ensuite mise 
en exergue avec un arriere-plan colore. Une zone de cellules expose la fonction 
findAll qui a pour argument l'objet descripteur de recherche et renvoie un objet 
conteneur contenant toutes les occurrences trouvees. Leur nombre est disponible 
dans la propriete Count de l'objet conteneur. Chaque occurrence est soit une cellule, 
soit une zone de cellules contenant chacune l'information recherchee. On recupere 
chaque occurrence par la methode getBylndex du conteneur ; avec OOoBasic, le 
getBylndex peut etre omis, comme si on indexait une variable tableau. 

rem Code09-04 . ods bibli : Rechercher Modulel 
Option Explicit 

Sub TrouverToutdansUneZoneO 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maZone As Object 

Dim jeCherche As Object, trouv As Variant, x As Long 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Composi teurs") 

maZone = maFeuille. getCell RangeByName("A2 :C117") 

jeCherche = maZone. createSearchDescriptor 

with jeCherche 

.SearchString = "Jean" 

1 rechercher les cellules contenant au moins ce texte 
.SearchWords = false 
end with 
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trouv = maZone. findAll (jeCherche) 

print "Nombre d ' occurrences : " & trouv. Count 

for x = 0 to trouv. Count -1 

trouv(x) .CellBackColor = RGB(255 , 200 , 255) 

MsgBox(trouv(x) . Absol uteName) 
next 
End Sub 

La structure Basic Wi th ... End Wi th evite de repeter le nom de la variable descrip- 
teur sur plusieurs lignes. Sans elle, on ecrirait : 

jeCherche . SearchStri ng = "Jean" 
jeCherche. SearchWords = true 

Vous remarquerez avec l'exemple du document de l'archive Zip telechargeable que la 
recherche de « Jean » donne quatre zones, la deuxieme etant deux cellules contigues : 
l'API renvoie le nombre minimal de zones. La fonction Tout rechercher dans l'inter- 
face utilisateur donne les memes resultats. La methode findAll n'est simple que 
pour effectuer un traitement global sur les zones obtenues. 



Rechercher successivement 

Un autre moyen de recherche consiste a trouver la premiere occurrence avec la 
methode f i ndFi rst de l'objet zone de cellules, puis a rechercher les occurrences sui- 
vantes avec la methode findNext jusqu'a echec de la recherche. On ne peut pas con- 
naitre immediatement le nombre total d'occurrences, mais on obtiendra successive- 
ment chacune des cellules. 

rem Code09-04 . ods bibli : Rechercher Module2 
Option Explicit 

Sub TrouverToutsuccessi vement() 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maZone As Object 

Dim jeCherche As Object, trouv As Variant 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 11 es . getByName("Composi teurs") 

maZone = maFeui 1 1 e . getCel 1 RangeByName("A2 : C117") 

jeCherche = maZone . createSearchDescri ptor 

with jeCherche 

.SearchString = "Dean" 

1 rechercher les cellules contenant au moins ce texte 
.SearchWords = false 
end with 
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trouv = maZone. findFirst(jeCherche) 
Do Until isNull (trouv) 

trouv. CellBackColor = RGB(255,200,255) 

MsgBox(trouv.Absol uteName) 

trouv = maZone. findNext (trouv, jeCherche) 
Loop 
End Sub 

Si la recherche ne trouve rien, l'objet posTrouve recoit la valeur Null et la boucle h est pas 
executee. Si elle trouve, posTrouve est alors un objet cellule. La recherche est relancee par 
f i ndNext, qui utilise en premier argument l'objet cellule precedemment trouve. 

II est possible de selectionner visuellement la zone trouvee, au lieu de changer la cou- 
leur de fond : 

monDocument . Cu r rentCont roller. Sel ect (posTrouve) 

Rechercher pour remplacer 

Lors d'une recherche progressive, la zone de texte posTrouve selectionne la cellule 
trouvee. Nous pourrions alors utiliser cet objet cellule pour analyser le type de con- 
tenu de la cellule, ou modifier le contenu ou le format a notre guise. Nous vous lais- 
sons faire une telle macro, a titre d'exercice. 

Remplacer systematiquement 

Dans le cas simple ou toutes les occurrences doivent etre systematiquement rempla- 
cees partout, les objets feuille et zone offrent la fonction replaceAll, qui effectue ce 
travail et renvoie le nombre de remplacements. Elle utilise un descripteur de rempla- 
cement, obtenu avec la methode createReplaceDescriptor, qui contient tous les 
elements du descripteur de recherche et ajoute ReplaceString, de type String, qui 
contient la chaine de caracteres a mettre a la place de celle qu'on recherche. 

rem Code09-04 . ods bibli : Remplacer Modulel 
Option Explicit 

Sub Rempl acerPartoutdanslZone() 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maZone As Object 

Dim jeCherche As Object, nbrFois As Long 

monDocument = Thi sComponent 

lesFeuilles = monDocument. Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Composi teurs") 

maZone = maFeuille. getCell RangeByName("A2 :C117") 

jeCherche = maZone. createReplaceDescriptor 
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with jeCherche 

.SearchString = "Johann" 
. ReplaceString = "Theodule" 

' rechercher les cellules contenant au moins ce texte 
.SearchWords = false 
end with 

nbrFois = maZone . replaceAll (jeCherche) 
print "Nombre de rempl acements : " & nbrFois 
End Sub 

La macro suivante modifie toutes les cellules de style Titrel d'une feuille pour leur 
affecter un autre style Resultat2. 

rem Code09-04 . ods bibli : Rempl acer Module2 
Option Explicit 

Sub Rempl acerStyl ePartoutdanslFeui 1 1 e() 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object 

Dim jeCherche As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 11 es . getByName("Composi teurs") 

jeCherche = maFeui 1 1 e . createRepl aceDescri ptor 

with jeCherche 

.SearchString = "Titrel" 

.ReplaceString = "Resultat2" 

.SearchStyles = true 
end with 

maFeuille. replaceAll (jeCherche) 
End Sub 

Dans une modification de styles, le nombre de remplacements nest pas fourni par 
replaceAll. 

Trier une zone 

Un objet zone de cellules fournit une methode de tri (en anglais Sort). Nous allons 
effectuer un tri sur la premiere colonne du tableau de la feuille Compositeurs. Voici 
l'ensemble du code, que nous expliquerons progressivement. 

rem Code09-03 . ods bibli : Calculs Module2 
Option Explicit 

Sub Tri erlCol onne() 

Dim monDocument As Object, lesFeuilles As Object 
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Dim maFeuille As Object, maZone As Object 

Dim ConfigTri (0) As New com. sun. star. table. TableSortField 

Dim DescrTri As Variant 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Composi teurs") 

maZone = maFeui 11 e . getCell RangeByName("Al : D118") 



With ConfigTri (0) 

.Field = 0 ' colonne A = "Norn, Prenom" 

.IsAscending = true 
End With 



DescrTri = maZone. createSortDescriptor 



setPropVal (DescrTr 
setPropVal (DescrTr 
setPropVal (DescrTr 
setPropVal (DescrTr 
setPropVal (DescrTr 
setPropVal (DescrTri 
maZone. Sort (DescrTri ()) 
End Sub 



"SortFields", ConfigTri ()) 
"IsSortCol umns" , false) 
"CopyOutputData" , false) 
"IsUserListEnabl ed" , false) 
"BindFormatsToContent" , false) 
"ContainsHeader" , true) 



Nous definissons la zone de tri dans le tableau en incluant la premiere ligne qui con- 
tient les en-tetes de colonnes. On aurait pu l'exclure. 

La methode de tri a besoin d'un descripteur de tri, obtenu par la methode 
createSortDescriptor, qui precise les conditions globales de tri. Parmi celles-ci, nous 
trouvons l'element SortFi el ds, qui contient un tableau (au sens d'une variable Basic) de 
descripteurs, un par colonne a trier. Nous allons maintenant decrire chaque descripteur. 

Un descripteur de tri par colonne est une structure com. sun. star. table. 
TableSortField composee des elements detailles dans le tableau 9-20. 

Tableau 9-20 Descripteur de tri par colonne 



Fi el d 


Long 


Rang de la colonne dans la zone de cellules ; valeur 0 pour la 
premiere colonne. 


IsAscendi ng 


Bool ean 


True pour un tri par ordre croissant. 


IsCaseSensitive 


Boolean 


True pour tenir compte de la casse des caracteres. 


FieldType 


Integer 


Type du champ (non utilise). 


CollatorLocale 


Object 


Langue utilisee pour les fonctions dependant de la localisation. 
Voir la notion de Locale dans le chapitre 7. 


Col 1 atorAl gori thm 


String 


Methode de tri. 
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L' element Fi el dType n'est pas utilise car chaque cellule de tableur indique le type de 
donnee quelle contient. Le tri croissant place les cellules numeriques avant les cel- 
lules de texte. 

L'element CollatorLocale est lui-meme une structure Locale. Pour les cas courants 
(francais, anglais, espagnol, allemand...) il n'est pas necessaire de le remplir. De 
meme, Col 1 atorAl gori thm peut etre omis car il n'y a actuellement pas de choix pos- 
sible (la seule valeur possible est al phanumeri c). 

Le descripteur global de tri est obtenu avec la methode createSortDescri ptor de 
l'objet maZone. Ce descripteur est un tableau (Array) de structures PropertyValue. 
Chacune de celles-ci comporte un nom et une valeur. Le tableau 9-21 liste ces pro- 
prietes. Les noms sont initialises par createSortDescri ptor, mais l'ordre des pro- 
prietes dans le tableau de structures depend de i'implementation. La routine utilitaire 
setPropVal recherche la propriete d'un nom donne et lui affecte la valeur qui est en 
argument. Cette routine, empruntee a l'annexe B, est recopiee dans la bibliotheque 
Standard, module Utilitai res, de notre document. 



Tableau 9-21 Descripteur global de tri 



Element 


Type 


Signification 


IsSortCol umns 


Boolean 


Fal se pour trier par colonne (intervertir les lignes). Valeur par 
defaut. 

True pour trier par lignes (intervertir les colonnes). 


SortFields 


Array(Object) 


Tableau des descripteurs de tri par colonne. 


ContainsHeader 


Boolean 


True si la zone contient les en-tetes de colonne. 


Bi ndFormatsToContent 


Boolean 


True pour deplacer les formats de cellules avec les cellules. 
Valeur par defaut. 


MaxFieldCount 


Long 


En lecture seule, nombre maximal de colonnes a trier, valeur 
actuelle = 3. 


CopyOutputData 


Boolean 


True pour mettre le resultat trie dans une autre zone. 
Valeur par defaut : Fal se. 


OutputPosition 


Object 


Position de la premiere cellule de la zone a utiliser pour le resultat. 


IsllserListEnabled 


Boolean 


True pour utiliser une liste de tri particuliere. 
Valeur par defaut : False. 


UserLi stlndex 


Long 


Precise la liste de tri utilisee. 



Affectez une valeur a chacun des indicateurs booleens du descripteur global, car ils 
ne sont pas tous initialises a Fal se. 

L'element IsSortCol umns, au nom particulierement mal choisi, indique si on trie par 
colonne (notre cas, le cas courant), ou si on trie des lignes (dans ce cas, le tableau aura 
des en-tetes de lignes et tout se passe comme si on avait tourne le tableau de 
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90 degres). Nous continuons sur notre exemple de tri de colonnes, sachant qu'il suffit 
de remplacer le terme « ligne » par « colonne » dans le deuxieme cas. 

L'element MaxFieldCount est pour nous une constante. Dans la version actuelle 
d'OpenOffice.org, on peut trier sur un maximum de 3 colonnes, comme on le verra 
dans l'exemple suivant. 

La position OutputPosition est obtenue avec la propriete CellAddress d'un objet 
cellule. 

Nous ne detaillerons pas le concept de UserLi stlndex. Les tris utilisateurs forment 
un tableau de chaines de caracteres, memorisees dans les proprietes du document. 

Une fois le descripteur global de tri initialise, la table est triee avec la methode Sort. Si 
vous executez la macro sur le document fourni dans le Zip telechargeable, vous pourrez 
voir comment s'effectue le tri avec ou sans prise en compte de la casse. Pour revenir a 
l'ordre initial de la table, utilisez le bouton Annuler sur la fenetre Writer, ou executez la 
macro TrierTableParLignes qui est dans le module 3 de la meme bibliotheque. 

Tri sur plusieurs colonnes 

Nous allons maintenant trier le meme tableau sur trois colonnes successivement. 
Nous utiliserons un tableau de trois descripteurs de colonnes, qui sont prises en 
compte dans le meme ordre que ces descripteurs. 

rem Code09-03 . ods bibli : Calculs Module3 
Option Explicit 

Sub Trier3Colonnes() 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maZone As Object 

Dim ConfigTri(2) As New com . sun . star . tabl e .Tabl eSortFi el d 

Dim DescrTri As Variant 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Composi teurs") 

maZone = maFeui 1 1 e . getCell RangeByName("Al : D118") 

Conf igTri (0) . Fi el d = 2 ' colonne C = "Naissance" 
Confi gTri (0) . IsAscendi ng = true 
ConfigTri(l) . Field = 3 ' colonne D = "Deces" 
Confi gTri (1) .IsAscendi ng = false 

Conf igTri (2) . Field = 0 ' colonne A = "Norn, Prenom" 
Confi gTri (2) . IsAscendi ng = true 

DescrTri = maZone . createSortDescri ptor 
setPropVal (DescrTri , "SortFi el ds" , ConfigTriQ) 
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setPropVal (DescrTri , "IsSortCol umns" , false) 
setPropVal (DescrTri , "CopyOutputData" , false) 
setPropVal (DescrTri , "IsllserLi stEnabl ed" , false) 
setPropVal (DescrTri , "Bi ndFormatsToContent" , false) 
setPropVal (DescrTri , "Contai nsHeader" , true) 
maZone . Sort (DescrTri ()) 
End Sub 

Le tri sur plusieurs colonnes ne prend en compte qu'une seule valeur pour le choix de 
la casse et pour le choix du Local e. 

Tris sur plus de trois colonnes 

La version 3.1 d'OpenOffice.org apporte une nouveaute dans le mecanisme de tri, 
qu'il soit fait par l'interface utilisateur ou par programmation : l'algorithme de tri est 
stable. Ceci veut dire que le tri conserve l'ordre des lignes dont les criteres ont des 
valeurs identiques. Ce n'etait pas le cas auparavant. Linteret est de pouvoir trier en 
plusieurs etapes, chacune effectuant un tri sur une a trois colonnes. On doit d'abord 
trier les colonnes « de poids faible », puis les colonnes de poids plus important, etc. 
Le document de l'archive Zip telechargeable comporte dans le Module4 un exemple 
de tri sur 6 colonnes, chacune triee par valeurs croissantes, l'importance des colonnes 
etant decroissante de la colonne A a la colonne F. La table de la feuille Tri 6 est 
d'abord triee sur les colonnes D a F, et le resultat trie sur les colonnes A a C. La 
feuille Tri 6-2 est une copie de sauvegarde, non triee. 



Pour aller plus loin 

Le tri de tableau est decrit dans la documentation API a l'interface XSortable et aux services 
SortDescri ptor2, Tabl eSortDescri ptor2 et SheetSortDescri ptor2. Les tris utilisa- 
teurs sont cites dans le service Gl obal SheetSetti ngs. 

Filtrer une zone de cellules 

Le filtrage standard d'une zone de cellules necessite un descripteur de filtrage (voir le 
tableau 9-22) renvoye par la methode createFi 1 terDescri ptor : 

descrFiltre = maZone . createFil terDescriptor (True) 

Quand 1' argument de createFil terDescri ptor vaut True, on obtient un descripteur 
vide ; avec un argument False le descripteur obtenu contient les valeurs precedem- 
ment utilisees pour la zone. 
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Tableau 9-22 Descripteur de filtrage 



IsCaseSensi ti ve 


Bool ean 


True pour tenir compte de la casse. 


SkipDuplicates 


Boolean 


True pour ne pas afficher les doublons. 


UseRegular Expressions 


Boolean 


True pour utiliser des expressions regulieres. 


CopyOutputData 


Boolean 


True pour copier le resultat du filtre ailleurs dans le document ; 
le formatage eventuel (par ex: 1 re ligne) est aussi recopie. 


SaveOutputPosi ti on 


Boolean 


Valide si CopyOutputData vaut True. 

True pour memoriser la position du resultat du filtre. Valeur par defaut : 
True. 


OutputPosition 


Object 


Adresse de la cellule ( com. sun . star .Cel 1 Address ) a partir de 
laquelle le resultat sera inscrit. 


Contai nsHeader 


Boolean 


True pour ne pas filtrer la premiere ligne (ou la premiere colonne). 


Orientation 


Integer 


Precise si I'operation est effectuee sur les colonnes ou les lignes ; cons- 
tants nommee, valeurs possibles : 

com . sun . star . tabl e .Tabl eOri entati on . COLUMNS 
com . sun . star . tabl e .Tabl eOri entati on . ROWS 


MaxFieldCount 


Long 


Lecture seule : le nombre maximum de champs de filtrage, actuellement 8. 


FilterFields 


Object 


Tableau de descripteurs de champs a filtrer. Voir le tableau 9-23. 



La propriete FilterFields (en realite les methodes setFilterFields et 
getFilterFields) donne acces a un tableau de descripteurs, un par condition de fil- 
trage. Chaque element du tableau stocke dans FilterFields est une structure 
com. sun. star . sheet .Tabl eFil terFi eld decrite dans le tableau 9-23. 

Tableau 9-23 Descripteur de champ a filtrer 



Connection 


Integer 


Lien avec la condition precedents : soit ET, soit OU ; constante nommee. 
ET: com . sun . star . sheet . Fi 1 terConnection . AND 
OU : com. sun. star. sheet. FilterConnection. OR 


Field 


Long 


Rang du champ concerne, a partir de zero. 


Operator 


Integer 


Operateur a appliquer ; constante nommee, voir tableau 9-24. 


IsNumeri c 


Boolean 


True si le champ Numeri cVal ue est a utiliser. 
Fal se si le champ Stri ngVal ue est a utiliser. 


Numeri cVal ue 


Double 


Valeur numerique de la condition. 


StringValue 


Stri ng 


ChaTne de caracteres de la condition. 
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Dans le champ Operator d'un descripteur de champ on retrouve les differentes con- 
ditions offertes avec l'interface utilisateur. On la precise par une constante nommee 
de la forme : 

| com . sun . star . sheet . Fi 1 terOperator . LESS EQUAL 

Tableau 9-24 Constantes d'operateur 



EMPTY 


Vide. 


notZempty 


Non vide. 


EQUAL 


Egal a. 


NOT_EQUAL 


Different de. 


GREATER 


Superieur a. 


GREATER_EQUAL 


Superieur ou egal a. 


LESS 


Inferieur. 


LESS_EQUAL 


Inferieur ou egal a. 


TOP_VALUES 


Les n plus grandes valeurs (n = champ Numeri cVal ue). 


TOP_PERCENT 


Les n pour cent plus grandes valeurs (n = champ Numeri cVal ue). 


BOTTOM_VALUES 


Les n plus petites valeurs (n = champ Numeri cValue). 


BOTTOM_PERCENT 


Les n pour cent plus petites valeurs (n = champ Numeri cVal ue). 



Le mecanisme de filtrage est celui appele Filtrage special dans l'interface utilisateur. 
Le champ Operator de chaque descripteur de champ relie les descripteurs ainsi : 

| (descrl AND descr2 AND descr3) OR (descr4 AND descr5) OR (descr6) OR etc... 

Passons maintenant a la pratique ! Nous allons filtrer dans la feuille Compositeurs 
ceux qui sont ne avant 1760 et decedes apres 1800, ou qui sont nes au moins en 1630 
et decedes avant 1700. Le resultat du filtrage sera copie dans la feuille Resultats a 
partir de la position D10. 



rem Code09-04 . ods 
Option Explicit 



bibli : Filtrer Modulel 



Sub filtrerZoneO 

Dim monDocument As Object, lesFeuilles As Object 
Dim maFeuille As Object, maZone As Object 

Dim monFiltre As Object, feuilleResu As Object, pointResu As Object 
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Dim champsFiltre(3) As New com. sun. star. sheet. TableFilterFi eld 
With champsFiltre(O) 

.Field = 1 ' colonne B : annee de naissance 
.Operator = com . sun . star . sheet . Fi 1 terOperator . LESS 
.IsNumeric = True 
. Numeri cVal ue = 1760 
End With 

With champsFiltre(l) 

.Connection = com. sun . star . sheet . Fi 1 terConnecti on .AND 
.Field = 2 ' colonne C : annee de deces 
.Operator = com . sun . star . sheet . Fi 1 terOperator . GREATER 
.IsNumeric = True 
. Numeri cValue = 1800 
End With 

With champsFiltre(2) 

.Connection = com. sun . star . sheet . Fi 1 terConnecti on .OR 
.Field = 2 ' colonne C : annee de deces 
.Operator = com . sun . star . sheet . Fi 1 terOperator . LESS 
.IsNumeric = True 
. Numeri cVal ue = 1700 
End With 

With champsFiltre(3) 

.Connection = com. sun . star . sheet . Fi 1 terConnecti on .AND 
.Field = 1 ' colonne B : annee de naissance 
.Operator = com . sun . star . sheet . Fi 1 terOperator . GREATER_EQUAL 
.IsNumeric = True 
. Numeri cValue = 1630 
End With 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Composi teurs") 

maZone = maFeuille. getCellRangeByName("Al:C117") 

monFiltre = maZone . createFil terDescriptor (True) 

With monFiltre 

. CopyOutputData = True ' essayer aussi : False 

. Contai nsHeader = True 

.Orientation = com. sun. star. table. TableOrientation. COLUMNS 
feuilleResu = lesFeuilles. getByName("Resultats") 
pointResu = feui 11 eResu . getCel 1 RangeByName("D10") 
.OutputPosition = poi ntResu . Cel 1 Address 
.FilterFields = champsFil tre() 
End With 

maZone . f i 1 ter(monFi 1 tre) 
End Sub 

Nous commencons par declarer le tableau de descripteurs de champs et a remplir 
chacun d'eux. La propriete Connecti on n'est pas significative pour le premier champ. 
Puis nous definissons la zone de cellules, comprenant l'en-tete, et nous recuperons 
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un descripteur de filtre vierge. Nous remplissons les champs pour lesquels la valeur 
par defaut ne convient pas. L'ensemble de la variable tableau champsFi 1 tre est trans- 
fere a la propriete FilterFields. Le filtrage est declenche en utilisant la methode 
f i 1 ter de la zone de cellules, en donnant en argument le descripteur de filtre. 

Le resultat apparait dans la feuille Resultats ; vous constaterez que le formatage de 
l'en-tete est recopie dans les donnees resultantes. On pourrait appliquer un autre fil- 
trage sur ce resultat, obtenant une autre table, etc. 

Relancez la macro apres avoir modifie en False la valeur de la propriete 
OutputPosition. Le filtrage s'effectue sur la table initiale. Et maintenant, comment 
supprimer ce filtrage pour retrouver la table complete ? Tout simplement, en filtrant 
la meme zone avec un descripteur vierge : 

rem Code09-04 . ods bibli : Filtrer Module2 
Option Explicit 

Sub SupprimerFiltreO 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maZone As Object, monFiltre As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 11 es . getByName("Composi teurs") 

maZone = maFeui 1 1 e . getCel 1 RangeByName("Al : C117") 

monFiltre = maZone. createFil terDescriptor(True) 

maZone . f il ter (monFil tre) 

End Sub 

Le filtre elabore utilise une zone de cellules pour indiquer les criteres de filtrage. 
Dans le fichier exemple nous avons defini dans la feuille Val Filtre les memes cri- 
teres de filtrage que precedemment. 

rem Code09-04 . ods bibli : Filtrer Module4 
Option Explicit 

Sub filtrerZoneSelonTableO 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 

Dim maZone As Object, fCrit As Object, criteres As Object 

Dim monFiltre As Object, feuilleResu As Object, pointResu As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

fCrit = lesFeuilles. getByName("Val Fil tre") 

criteres = fCrit.getCellRangeByName("C3:E9") 

maFeuille = 1 esFeui 11 es . getByName("Composi teurs") 
maZone = maFeui 1 1 e . getCel 1 RangeByName("Al : C117") 
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monFiltre = criteres. createFilterDescriptorByObject(maZone) 

With monFiltre 

.CopyOutputData = True ' essayer aussi : False 
.Contai nsHeader = True 

.Orientation = com. sun. star. table. TableOrientation. COLUMNS 
feuilleResu = lesFeuilles.getByName("Resultats") 
pointResu = feui 11 eResu . getCel 1 RangeByName("D10") 
.OutputPosition = poi ntResu . Cel 1 Address 
End With 

maZone . f i 1 ter (monFi 1 tre) 
End Sub 

Nous utilisons la methode createFi IterDescri ptorByObject de la zone contenant 
les criteres pour obtenir un descripteur de filtrage initialise avec les champs de filtre 
correspondants, ce qui simplifie un peu le codage mais surtout permet d'utiliser des 
criteres de filtre definis par l'utilisateur sur sa feuille. Vous remarquerez que la zone 
lue pour les criteres peut aller au-dela des lignes remplies, sans consequence. 



Fonctionnalites generates de Calc 

Dans cette partie, nous allons aborder d'autres possibilites offertes par un document 
Calc. Rappelons que l'importation d'un fichier CSV dans une feuille de document 
Calc est decrite au chapitre 7. 

Activer le calcul des formules 

Le calcul des valeurs de cellules est normalement effectue automatiquement apres la 
modification d'une cellule et pour les cellules qui dependent de celle-la. Dans un 
document tableur assez complexe, le temps de recalcul des cellules peut etre non 
negligeable et ralentir 1' execution des macros. L'objet document nous donne plu- 
sieurs moyens de maitriser les conditions de recalculs. 

Determiner si le recalcul automatique est actif : 

if monDocument . isAutomaticCalculationEnabled then 

1 le recalcul automatique est actuell ement active 
end if 

Inhiber, puis activer le recalcul automatique : 

1 inhiber le recalcul automatique 
monDocument . enabl eAutomati cCal cul ation (f al se) 
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' - - effectuer divers travaux - - 
' activer le recalcul automatique 
monDocument . enabl eAutomaticCal cul at ion (true) 

Recalculer seulement les formules qui ne sont pas a jour : 
monDocument. calculate 

Recalculer toutes les formules du tableur : 
monDocument . cal cul ateAl 1 

Utiliser une fonction de Calc 

Basic dispose d'un certain nombre de fonctions, mais Calc en possede de nombreuses 
autres. Dans vos algorithmes de macros, il est inutile de programmer des fonctions 
qui existent dans Calc : il suffit de les appeler. 

Notre premier exemple va calculer le PPCM (Plus Petit Commun Multiple) de plu- 
sieurs nombres. II utilise une petite fonction que nous appellerons de maniere tres 
originale : PPCM. 

rem Code09-03 . ods bibli : Fonctions Modulel 
Option Explicit 

Sub UtiliserFonctionCalcO 
Dim params As Variant 
params = Array(35 , 75 , 1110) 
print PPCM(paramsO) 

' appel sans utiliser de variable i ntermedi ai re 
print PPCM (Array (17, 525, 357, 76, 54)) 
End Sub 



Function PPCM(liste As Variant) As Long 

Dim acceder As Object 

accede r = CreateUnoService("com . sun . star . sheet . FunctionAccess") 
PPCM = acceder. cal 1 Function("LCM" , liste) 

End Function 

Notre fonction PPCM obtient un objet lui permettant d'utiliser le service d'acces aux 
fonctions Calc. La methode call Function de ce service appelle une fonction Calc 
(son nom interne est en premier argument, les arguments de la fonction sont en 
deuxieme argument), puis renvoie le resultat simplement comme resultat de notre 
fonction. 
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La routine principale montre deux exemples d'appels. Le premier utilise la fonction 
Basic ArrayO pour creer et initialiser facilement un tableau unidimensionnel qui 
contient les valeurs numeriques dont on recherche le PPCM. Ce tableau est ensuite 
transmis a notre fonction PPCM, qui s'empresse de le transmettre a la fonction Calc. 

Le deuxieme appel est similaire au premier, mais utilise directement le resultat de la 
fonction Array sans variable intermediate. 

De ces appels, il faut retenir que le deuxieme argument de cal 1 Functi on est une liste 
(un tableau unidimensionnel). Chaque element de la liste est un argument pour la 
fonction Calc. Un argument de fonction Calc peut admettre une valeur ou une serie 
de valeurs ; la serie de valeurs se traduit en un tableau uni ou bidimensionnel. 

A RETENIR Utiliser une fonction de Calc 

Vous avez sans doute remarque que I'exemple n'utilise aucune reference a une feuille ou a un document 
Calc. Effectivement, il fonctionne aussi bien dans un document Writer, Draw, ou Impress. 

Reste un probleme : comment connaitre le nom interne d'une fonction Calc ? La 
feuille NomsFonctions du document Code09-01.ods liste les correspondances de 
noms de fonctions. Vous remarquerez que l'equivalent anglais de certaines fonctions 
est un nom interne complexe. 

Le deuxieme exemple montre comment appeler la fonction TAUX. EFFECTIF qui 
necessite deux arguments. La variable pa rams est definie comme un tableau unidi- 
mensionnel a deux elements, chacun recevant un argument. 

rem Code09-03 .ods bibli : Fonctions Module3 
Option Explicit 

Sub Fonction2Arguments() 

Dim acceder As Object, resu As Double 

Dim params(l) ' deux arguments a transmettre 

acceder = CreateUnoServi ce ("com . sun . star . sheet . Functi onAccess") 
params(O) = 9.75/100 ' taux nominal 
params(l) = 12 ' nombre de paiements annuels 
resu = acceder. cal 1 Function("EFFECTIVE" , paramsO) 
print "Taux effectif : " & Format(resu , "##.##%") 
! End Sub 

Creer une nouvelle fonction pour Calc 

Si les nombreuses fonctions proposees par Calc ne vous suffisent pas, ecrivez une 
fonction qui realise ce dont vous avez besoin. Deux methodes sont possibles : 
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• Ecrire un add-in, ce qui permet une parfaite integration, y compris dans l'assis- 
tant de fonctions, mais necessite un langage capable de creer un composant UNO 
(C++, Java, Python) etbeaucoup de connaissances techniques. 

• Ecrire la fonction en Basic. Les fonctions dans un autre langage de script ne sont 
pas utilisables depuis une formule Calc. 

Nous allons commencer simplement, avec une fonction qui remplace un nombre a 
deux chiffres par une annee du XX e siecle. Si le nombre est negatif ou superieur 
a 2099, on veut declencher une erreur. La fonction est definie dans la bibliotheque 
Standard, nous expliquerons pourquoi un peu plus loin. 

rem Code09-03 . ods bibli : Standard Modulel 
Option Explicit 

' nouvelle fonction pour Calc 

Function Annee2( arg As Long) As Variant 

if (arg<0) or (arg>2099) then 

Annee2 = "Annee ?" 
elseif arg<100 then 

Annee2 = 1900 +arg 
el se 

Annee2 = arg 
end if 
End Function 

La fonction renvoie normalement un nombre, sauf en cas d'argument incorrect ou 
elle renvoie un texte d'erreur. Suivant la formule contenue dans la cellule, soit le texte 
sera affiche, soit le melange de texte et de valeur numerique provoquera une erreur. 
Votre fonction peut comporter plusieurs arguments, comme dans cet exemple qui 
calcule un volume a partir de trois dimensions : 

rem Code09-03 . ods bibli : Standard Module2 
Option Explicit 

' nouvelle fonction pour Calc 

Function Volume(x As Double, y As Double, z As Double) As Double 
Volume = x *y *z 
End Function 

Lappel de cette fonction se fera par une formule du genre : =Volume(B3;C17;H28). 
N'oubliez pas que, dans une formule, les arguments d'une fonction sont separes par 
un point-virgule, alors que dans la declaration de fonction Basic ils sont separes par 
une virgule. 
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Enfin, si un argument utilise les valeurs d'une zone de cellules, il apparait sous la 
forme d'un tableau a deux dimensions. Ce dernier exemple montre comment obtenir 
les valeurs successives de la zone de cellules. II fonctionne pour une zone rectangu- 
laire ou reduite a une dimension. 

rem Code09-03 .ods bibli : Standard Module3 
Option Explicit 

' nouvelle fonction pour Calc 

Function maSomme(arg As Variant) As Double 

Dim colonne As Long, ligne As Long, resu As Double 

resu = 0 

for ligne = LBound(arg) to UBound(arg) 

for colonne = LBound(arg, 2) to UBound(arg, 2) 
resu = resu + arg(ligne, colonne) 

next colonne 
next ligne 
maSomme = resu 
End Function 



Creer une fonction matricielle 

Une fonction matricielle effectue des calculs sur une zone de cellules et inscrit le 
resultat dans la zone de cellules situee a l'emplacement de la formule. Void une fonc- 
tion matricielle qui ajoute a chaque cellule de la matrice la valeur donnee en 
deuxieme argument. 

rem Code09-03 . ods bibli : Standard Module4 
Option Explicit 

Function ajouter(arg As Variant, valeur) As Variant 
Dim colonne As Long, ligne As Long 

Dim xMin As Long, xMax As Long, yMin As Long, yMax As Long 

yMin = LBound(arg, 1) 
yMax = UBound(arg, 1) 
xMin = LBound(arg, 2) 
xMax = UBound(arg, 2) 

Dim resul tatCyMin to yMax, xMin to Xmax) As Variant 

for ligne = yMin to yMax 
for colonne = xMin to xMax 

resul tat(l igne, colonne) = arg(ligne, colonne) +valeur 

next colonne 
next ligne 

ajouter = resul tat() 

End Function 
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Le premier argument de notre fonction (variable arg) est une zone de cellules, done 
elle apparait en Basic sous forme d'un tableau a deux dimensions. Le resultat de la 
fonction matricielle sera lui aussi un tableau a deux dimensions, e'est pourquoi nous 
declarons ce resultat de type Variant. Les dimensions exactes du tableau sont con- 
nues a 1' execution avec les fonctions LBound et UBound. Ceci nous sert a declarer une 
variable interne, resultat, comme tableau aux memes dimensions. Une fois calorie, 
ce tableau devient le resultat de la fonction. 

Void comment utiliser cette fonction. Supposons tout d'abord que la zone B2:C5 
contienne les donnees de la matrice. Dans une cellule, par exemple en E10, ecrivez la 
formule =A10UTER(B2 : C5 ; 1000) puis validez-la avec Ctrl + Maj + Entree. La formule 
s'affiche alors entouree d'accolades et le resultat apparait dans la zone E10:F13. Si 
vous souhaitez modifier la formule, selectionnez d'abord la zone resultat, modifiez- 
la, puis validez avec Ctrl + Maj + Entree. 

Limitations des fonctions pour Calc 
Transmission des arguments de la formule 

A travers ces exemples vous avez constate que, lorsqu'une formule Calc transmet une 
adresse de cellule, par exemple =Annee2(B17), la fonction ne recoit jamais l'objet cellule 
mais seulement sa valeur, au contraire des fonctions dans Microsoft Excel. Le seul moyen 
de recuperer l'objet cellule est de transmettre explicitement en arguments les coordonnees 
de la cellule. II en est de meme pour une zone de cellules. C'est une difference majeure de 
comportement avec Excel, et cela complique le portage de fonctions Excel vers Open- 
Office, org car on peut etre oblige de changer la syntaxe d'appel de la fonction. 

Que peut-on faire avec une fonction pour Calc ? 

Une fonction Calc sert a renvoyer une valeur qui sera utilisee dans la formule de la 
cellule utilisant cette fonction. La valeur renvoyee est soit un nombre de type Doubl e, 
soit un type Stri ng, soit un tableau de Doubl e ou Stri ng (fonction matricielle). 

Insistons : une fonction Calc ne sert qua renvoyer une valeur qui sera utilisee dans la 
formule de la cellule. C'est pourquoi vous ne pouvez pas modifier la cellule en cours 
(par exemple la colorier) ou modifier une autre cellule : l'API ignore ces actions. 

Impact des bibliotheques Basic 

Votre fonction Basic doit etre accessible par Calc. Cela signifie que la bibliotheque dans 
laquelle se trouve votre fonction doit etre deja chargee quand les formules sont evaluees ; 
or revaluation des formules d'un document Calc se produit avant le declenchement de 
l'evenement « chargement du document ». Si vous ne placez pas votre fonction dans la 
bibliotheque Standard de votre document, revaluation ne pourra se faire lors du charge- 
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ment, et toutes les cellules utilisant la fonction produiront une erreur. La meme situation 
peut arriver avec une bibliotheque de Mes macros. Pour cette raison, une fonction pour 
Calc sera habituellement creee dans la bibliotheque Standard de Mes macros ou dans la 
bibliotheque Standard du document Calc qui l'utilise. 

Si vous desirez que votre fonction XX soit dans une bibliotheque BBB, vous devez creer 
une autre fonction YY dans Standard qui se contentera de charger systematiquement 
la bibliotheque BBB puis d'appeler la fonction XX en lui transmettant ses arguments, 
et renvoyer le resultat obtenu par la fonction XX. Les formules de Calc appelleront la 
fonction YY. Void les declarations d'une telle fonction. 

' Bibliotheque BBB du document, protegee par un mot de passe 

Function Polynome2(x As Double, a As Double, b As Double, c As Double) _ 

As Double 
Polynome2 = a*x*x + b*x +c 
End Function 



1 Bibliotheque Standard du document 

Function Polynome(x As Double, a As Double, b As Double, c As Double) 

As Double 
BasicLibraries.loadLibraryO'BBB") 

IPolynome = Polynome2(x, a, b, c) 
End Function 

Exemple d'utilisation dans une cellule Calc : =P0LYN0ME(B2 ; A3 ; A4 ; B4) 

Inserer un lien hypertexte 

Cette macro insere un lien hypertexte dans le texte d'une cellule. 

rem Code09-09.ods bibli : Standard Modulel 
Option Explicit 

Sub InsererLi enHyperTexte() 

Dim monDocument As Object, maFeuille As Object 
Dim maCellule As Object, monCurseur As Object 
Dim monHyper As Object 

monDocument = Thi sComponent 
I maFeuille = monDocument. Sheets. getByName("HyperTexte") 
maCellule = maFeuille. getCel 1 RangeByName("B2") 

monHyper = monDocument . createInstance("com . sun . star . text .TextFiel d . URL") 
monHyper. URL = "http://fr.openoffice.org" 
monHyper. Representation = "OpenOffice.org France" 
monCurseur = maCel 1 ul e . createTextCursor 



Les documents Calc 

Chapitre 9 



monCurseur . gotoEnd(fal se) 

maCellule.insertTextContent(monCurseur, monHyper, false) 
End Sub 



Les liens vers un autre classeur 

Nous ne traitons pas ici des liens hypertextes, mais de ces trois types de liens: 

• lier a une feuille d'un autre classeur ; 

• lier a une zone de cellules d'un autre classeur ; 

• lien DDE (par copier-coller special avec lien vers une cellule d'un autre classeur, 
disponible seulement sous MS-Windows). 

Nous verrons que ces liens sont memorises dans trois conteneurs du document Calc, 
respectivement : SheetLi nks, AreaLi nks, DDELi nks. Chaque lien est accessible par la 
methode getBylndex du conteneur, ou en Basic par une pseudo-indexation du con- 
teneur. 

Les exemples complets sont dans l'archive Zip telechargeable, dans le fichier 
Code09-05 .ods. Dans les macros, l'adresse du fichier lie (SourceLiens .ods) doit etre 
adaptee a votre systeme. 

Lier a une feuille d'un autre classeur 

Quand on lie une feuille d'un classeur A a la feuille d'un classeur B, le contenu exis- 
tant de la feuille du classeur A sera ecrase. Seul le contenu des cellules est copie, pas 
les images, dessins, formulaires. Le lien est realise par la methode link de la feuille 
receptrice. Cet exemple resume le principe : 

adrAutreDoc = ConvertToURL ("C:\Docs OpenOffice\SourceLiens.ods") 

Const nomFiltre = "" ' nom du filtre eventuel 
Const optionsFiltre = "" ' options du filtre 
Const nomFeuilleSource = "Compositeurs" 

' la liaison va ecraser le contenu existant de cette feuille ! 
maFeuille = monCalc. Sheets. getByName("listeCompositeurs") 
maFeuille.link(adrAutreDoc, nomFeuilleSource, nomFiltre, optionsFiltre, 
com . sun . star . sheet . SheetLi nkMode . VALUE ) 

Pour lier a une feuille d'un document Calc ou Excel, il n'est pas necessaire de preciser 
un filtre, OpenOffice.org se debrouille tout seul. Dans les autres cas, le nom du filtre 
et ses options eventuelles doivent etre specifies. Le cas le plus courant est le lien a un 
document au format CSV ; bien que ce dernier soit un simple fichier texte, apres 
importation il est traite comme un classeur a une seule feuille et on peut done effec- 
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tuer un lien vers celle-ci (et il n'est pas besoin de preciser le nom de cette feuille). 
L'importation de CSV est traitee au chapitre 7. 

Le dernier argument de la methode link permet de recopier soit seulement les 
valeurs des cellules, comme dans l'exemple, soit les valeurs et les formules dans les 
cellules en utilisant a la place : 

com . sun . star . sheet . SheetLi nkMode . NORMAL 

Le lien realise est memorise dans le conteneur SheetLi nks du document Calc. Ce 
conteneur contient un lien pour chaque document externe lie, et un seul lien si le 
meme document est lie pour plusieurs feuilles. On reconnait le lien a sa propriete 
URL, qui correspond a l'adresse du document lie. 

Dim liens As Object, unLien As Object, n as Long 
liens = monCalc. SheetLi nks 
For n = 0 to liens. Count -1 
unLien = liens(n) 
if adrAutreDoc = unLi en . URLthen 

MsgBox("Lien trouve") 1 utiliser eventuel 1 ement le lien 
Exit For 
end if 
Next 

Lier a une zone d'un autre classeur 

Les zones de cellules liees existant dans un classeur sont memorisees dans le conte- 
neur AreaLinks du classeur. La methode insertAtPosition de ce conteneur permet 
de lier une zone de cellules du document recepteur a une zone de cellules dans un 
autre classeur. 

adrAutreDoc = ConvertToURL("C:\Docs OpenOffice\SourceLiens.ods") 
Const nomFiltre = "" ' nom du filtre eventuel 

Const optionsFiltre = "" ' options du filtre 
Const zoneSource = "Refs.Al:B6" 

maFeuille = monCal c . Sheets . getByName("zoneExterne") 
' cellule d'arrivee, coin haut-gauche de la zone 
arrivee = maFeuille. getCel 1 RangeByName("D3") .Cell Address 
liens = monCalc. AreaLinks 

1 iens . insertAtPosition(arrivee, adrAutreDoc, zoneSource, 

nomFiltre, optionsFiltre) 

La zone source peut etre specifiee par ses coordonnees ou par son nom si c'est une 
zone nommee. Nos essais avec un lien d'un document CSV n'ont pas permis une 
importation correcte. 
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Le lien realise, memorise dans le conteneur AreaLinks du document Calc, expose 
une propriete URL qui correspond a l'adresse du document lie, et une propriete 
DestArea qui contient la zone de destination sous forme d'une structure 
Cell RangeAddress. II suffit de comparer le coin haut-gauche de la zone de destina- 
tion avec celui de la zone liee, puisqu'il ne peut etre lie qua un seul element externe. 

Dim unLien As Object, zarn'v As Object, n as Long 

For n = 0 to liens. Count -1 
unLien = liens(n) 
zarriv = unLi en . DestArea 
if (ami vee . Sheet = zarri v . Sheet) and _ 

(arrivee. Column = zarriv. StartColumn) and _ 
(arrivee.Row = zarriv. StartRow) then 
MsgBox("Lien trouve") ' utiliser eventuell ement le lien 
Exit For 
end if 
Next 

Lier par DDE 

Un lien DDE s'effectue par une formule dans la cellule. En fait, il s'agit d'une for- 
mule matricielle, car on peut lier les cellules d'une zone aux cellules d'une zone 
homologue dans le fichier source. Le cas d'une seule cellule est done une zone a une 
cellule. Traitons le cas general : 

Const zoneSource = "Composi teurs . B55 : B60" 
Const modeDDE = 0 ' valeurs possibles : 0, 1, 2 
adrAutreDoc = "C:\Docs OpenOff i ce\SourceLi ens . ods" 

maFeuille = monCal c . Sheets . getByName("Sommai re") 
maZone = maFeui 1 1 e . getCel 1 RangeByName("C18 : C23") 
maZone .ArrayFormula = "=DDE(""soffi ce"" ; """ & adrAutreDoc & _ 
& zoneSource & & modeDDE & ")" 

Remarquez l'adresse du document source : e'est une adresse systeme MS-Windows 
et non une URL, car DDE n'existe que pour ce systeme. 

On obtient l'objet zone de cellules destinataires, puis on remplit sa propriete 
ArrayFormula avec la formule comportant la fonction DDE. Nous avons deja vu dans 
la section « Formule matricielle » cette propriete. La fonction DDE comporte quatre 
arguments, detailles dans l'aide F1 (cherchez DDE, fonction). La syntaxe Basic 
impose de doubler les guillemets a l'interieur d'une chaine, ce qui complique l'ecri- 
ture. Le resultat de la macro est un seul lien ajoute dans le conteneur DDELi nks, bien 
qu'il concerne une zone de cellules. 
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RafraTchir les liens 

Un lien vers une feuille ou vers une zone peut etre rafraichi periodiquement : 
unLien.RefreshPeriod = 60 ' rafraichi r toutes les 60 secondes 

La methode refresh du lien sert a declencher un rafraichissement immediat. Le 
principe est identique pour les trois types de liens, comme le montre ce codage : 

Sub MettreAjourTousLiensO 
Dim monCalc As Object 
monCalc = Thi sComponent 

Ma j Li ens (monCal c . DDELi nks) 
Maj Li ens(monCal c . AreaLinks) 
Ma j Li ens (monCal c . Sheet Li nks) 

MsgBox("Mise a jour effectuee") 
End Sub 

Sub Maj Li ens (liens As Object) 
Dim unLien As Object, n As Long 
for n = 0 to liens. Count -1 
unLien = liens(n) 
unLi en . refresh 
next 
End Sub 

Supprimer les liens 

Pour supprimer le lien vers la feuille liee (et conserver la copie des cellules) il faut 
mettre a NONE le Li nkMode de la feuille receptrice : 

maFeuill e . LinkMode = com. sun. star. sheet. SheetLi nkMode. NONE 

Pour supprimer un lien de zone particulier, on doit d'abord le retrouver dans le con- 
teneur AreaLinks comme indique plus haut, puis utiliser la methode removeBylndex 
avec l'index obtenu. 

Pour supprimer tous les liens de zone, utilisez de maniere repetee la methode 
removeBylndex pour enlever le premier lien du conteneur : 

liens = monCalc. AreaLinks 
Do While liens. Count > 0 
1 i ens . removeBylndex (0) 

Loop 
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Un lien DDE est une formule matricielle. Pour le supprimer en gardant la valeur il 
faut imposer dans cette cellule la valeur reelle, ce qu'on peut realiser avec la propriete 
DataArray, deja vue dans la recopie d'une tableau de cellules. 

Dim donnees As Variant 
donnees = maZone . DataArray 

maZone .DataArray = donnees ' on garde les valeurs 

La variable intermediate donnees est necessaire pour que les formules soient ecra- 
sees. Le meme principe peut etre utilise pour un DDE d'une seule cellule. 

Utiliser un Listener 

Dans le jargon OpenOffice.org, le mecanisme de surveillance de certains evenements 
est appele Listener, il est decrit au chapitre 14. Nous allons presenter ici quelques 
applications. 

Surveiller la modification d'une cellule 

Le principe est de « mettre sur ecoute » toute modification du contenu d'une cellule. 
Dans le document Code09-10.ods nous appliquons un ecouteur de modification sur 
la cellule C5 Feuille2, et sur la cellule B7 Feuille3. Initialement, la cellule B7 depend 
de la cellule D5 de la meme feuille, et de la cellule B5 Feuille2. 

rem Code09-10 . ods bibli : Ecouter Modulel 
Option Explicit 

Global ecouteurCellule As Object 

Global cell ul el As Object, cellule2 As Object 

Sub lancerEcouteCellules 

Dim feuilles As Object, feui 1 1 eCel 1 ul e As Object 
feuilles = ThisComponent. Sheets 

ecouteurCellule = CreateUnoListener( "MC ", 

"com. sun. star. util .XModi fyLi stener" ) 

feui 11 eCel 1 ul e = feui 1 1 es . getByName("Feui 11 e2") 
cell ul el = feui 1 1 eCell ul e . getCel 1 RangeByName("C5") 
eel 1 ul el . addModi fyLi stener (ecouteurCel 1 ul e) 
feui 11 eCel 1 ul e = feui 1 1 es . getByName("Feui 11 e3") 
cellule2 = f eui 1 1 eCell ul e . getCel 1 RangeByName("B7") 
eel 1 ul e2 . addModi fyLi stener (ecouteurCel 1 ul e) 
MsgBox "Cellules C5 et B7 sur ecoute !" 
End Sub 
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Sub arreterEcouteCel 1 ul el 

eel 1 ul el . removeModi f yLi stener (ecouteurCel 1 ul e) 

MsgBox("Fin d'ecoute de la cellule C5 !" ) 
End Sub 



Sub arreterEcouteCel 1 ul e2 

eel 1 ul e2 . removeModi f yLi stener (ecouteurCel 1 ul e) 

MsgBox("Fin d'ecoute de la cellule B7 !" ) 
End Sub 

' detection d'une modification de contenu 
Sub MC_modified(evt As Object) 
Dim laCellule As Object 
laCellule = evt. Source 

MsgBox("Cellule : " & laCellule.AbsoluteName & chr(13) & 
"Valeur : " & laCellule. Value & chr(13) & _ 
"Texte : " & 1 aCell ul e . Stri ng & chr(13) & _ 
"Formule : " & 1 aCell ul e . Formul aLocal ) 

End Sub 



Sub MC_disposing(evt As Object) 
1 routine obligatoire, meme vide ! 
End Sub 

Nous devons declarer en Global l'objet ecouteur et chaque objet cellule, car ils seront 
utilises dans des macros lancees separement, done ils doivent persister entre deux 
macros. La routine Basic CreateUnoLi stener sert a obtenir un ecouteur d'interface 
XModif yLi stener ; le premier argument precise le prefrxe qui sera utilise pour les 
routines d'evenement ; nous avons choisi MC_. La methode addModifyLi stener d'une 
cellule sert a lui affecter l'ecouteur ; la deconnexion de l'ecouteur se fait par la 
methode removeModi f yLi stener. 

La routine MC_modified est declenchee sur l'evenement de modification, la source de 
l'evenement est l'objet cellule concerne. La routine MC_disposing est obligatoire car 
eventuellement declenchee par l'API lors de la liberation de l'ecouteur. 

Laisser I'utilisateur selectionner une zone de cellules 

Dans l'assistant de fonctions Calc, ou dans la constitution d'un diagramme, l'inter- 
face utilisateur utilise une petite fenetre speciale pour permettre a I'utilisateur de 
selectionner une zone (figure 9-1). 



Figure 9-1 

Fenetre de selection de zone 
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On peut reproduire ceci en Basic, grace a l'interface XRangeSelecti on Listener, 
obtenue via le controleur actuel du document. Un tableau de PropertyVal ue (voir 
tableau 9-25) precise la maniere dont la selection s'effectuera. 

Tableau 9-25 Options pour la selection 



Title 


Stri ng 


Titre de la fenetre, complete a I'affichage par le texte «: Plage». 


Initial Value 


Stri ng 


Zone proposee au depart. Ecrire cette adresse de zone en absolu car toute 
zone selectionnee sera renvoyee en adressage absolu. 


SingleCellMode 


Boolean 


True pour n'autoriser que la selection d'une seule cellule. 
Fal se pour autoriser la selection d'une seule zone de cellules. 


CI oseOnMouseRel ease 


Boolean 


True : la selection est prise en compte au relachement du bouton de souris. 
Fal se : la selection est prise en compte en cliquant le bouton «Reduire». 



Dans l'exemple de demonstration le Listener est mis en place, les options sont rem- 
plies puis le mecanisme lance par la methode startRangeSelection. La macro entre 
alors dans une boucle d'attente executee 10 fois par seconde dont elle sort lorsqu'une 
variable commune a ete modifiee par un des gestionnaires d'evenements, ou au bout 
d'un certain temps ; le Listener est alors supprime. On distingue un evenement 
aborted (annulation, l'utilisateur a clique sur le X de la fenetre), et un evenement 
done (l'utilisateur a clique sur le bouton Reduire de la fenetre). Dans ce dernier cas, on 
recupere les coordonnees de la zone sous forme de chaine de caracteres. Si necessaire, 
on peut obtenir l'objet zone de cellules a partir de cette adresse textuelle, en extrayant 
la feuille et les coordonnees de cellule. La methode abortRangeSelection permet 
d'annuler a tout moment l'attente d'action utilisateur ; ici nous l'employons quand un 
certain delai s'est ecoule. 



rem Code09-10 . ods 
Option Explicit 



bibli : Ecouter Module2 



Private selectionFinie As Boolean, laSelection As String 

Sub laisserUtilisateurChoisi rZone() 

Dim props (3) As new com . sun . star . beans . PropertyVal ue 

Dim monCalc As Object, calcControle As Object 

Dim surveilleZone As Object, t As long 

Const tMax = 20000 1 millisecondes 

monCalc = Thi sComponent 
calcControle = monCalc. Cur rentController 
surveilleZone = createUnoListener("noterZone _", 
"com . sun . star . sheet . XRangeSel ectionLi stener ") 

selectionFinie = False 
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laSelection = "" 
t = 0 

cal cCont rol e . addRangeSel ectionLi stener (surveill eZone) 

props(O) .Name = "Title" 

props(O) . Val ue = "Premier argument " ' sera complete par ": Plage" 

props(l) . Name = "CloseOnMouseRelease" 

props(l) . Val ue = False 

props(2) . Name = "InitialValue" 

props(2) .Value = "$Feui 11 e2 . $B$5 : $D$7" 

props(3) . Name = "SingleCellMode" 

props(3) . Val ue = False 

cal cCont rol e . startRangeSel ection (props ()) 

Do ' attendre 1 'action utilisateur 
wait 100 
t = t +100 

if t > tMax then cal cControle.abortRangeSel ection 

Loop Until sel ecti onFi ni e 

cal cControle . removeRangeSel ecti onLi stener (surveil leZone) 

if Len(laSelection) > 0 then 

MsgBox("Zone selectionnee : " & laSelection) 
elseif t <= TMax then 

MsgBox("Vous avez annule la selection", 64) 
el se 

MsgBox("Vous avez depasse le temps autorise", 64) 
end if 
End Sub 



Sub noterZone_done(evt As Object) 
laSelection = evt . RangeDescri ptor 

selectionFinie = True ' pour sortir de la boucle d'attente 
End Sub 

Sub note rZone_abor ted (evt As Object) 

selectionFinie = True ' pour sortir de la boucle d'attente 
End Sub 



Sub note rZone disposing (evt As Object) 
1 routine obligatoire, meme vide ! 
End Sub 

Le controleur courant donne aussi acces a l'interface 
XRangeSel ectionChangeLi stener, qui permet de gerer l'evenement de changement 
de selection afin de traiter plusieurs zones. 
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Autres surveillances 

II est possible de surveiller la feuille courante ou les changements de selection a partir 
du controleur en cours. Mais certaines manipulations de l'utilisateur, notamment le 
passage en mode Apercu d'impression, entrainent des changements sur le controleur 
qui font perdre le Listener et peuvent provoquer un plantage d'OpenOffice. Le sujet 
est tres complexe (voir le message http://www.openoffice.org/servlets/ 
ReadMsg?list=dev&msgNo=21 148), et nous n'avons pas vu de solution sure. 

Control es de formulaires lies a Calc 

Certains controles de formulaires peuvent modifier une cellule de Calc, ou dependre 
d'une cellule de Calc. Reportez-vous au chapitre 13 pour plus d'information. 



Imprimer 

Le mecanisme general d'impression est decrit au chapitre 7. Nous traiterons ici des 
particularites de Calc. 

Zones d'impression 

Les zones a imprimer (interface utilisateur Format>Zones d'impression) sont definies au 
niveau d'une feuille dans la propriete Pri ntAreas. Elle recoit un tableau de coordonnees 
de zones d'impression. Ces coordonnees sont obtenues avec la propriete RangeAddress 
de chaque zone. Limpression se fera a raison d'une page (au moins) par zone. 

rem Code07-02 . ods bibli : Imprimer Module4 
Option Explicit 

Sub ImprimerZonesO 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeui lie As Object, maZone As Object 

Dim PropsO As New com. sun. star. beans. PropertyValue 

Dim adrZones(l) As New com. sun. star. table. Cell RangeAddress 

monDocument = Thi sComponent 
lesFeuilles = monDocument . Sheets 
maFeuille = 1 esFeui 11 es . getByName("Meteo") 

maZone = maFeui 11 e . getCel! RangeByName("B4 : E6") 
adrZones(O) = maZone . RangeAddress 
maZone = maFeui 1 1 e . getCel 1 RangeByName("C6 : K8") 
adrZones(l) = maZone . RangeAddress 
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maFeui lie. Pri ntAreas = adrZones() 

"if MsgBox(" Imp rimer ?", 36) = 6 then 

' PropsO est vide, pas d'option particuliere 

monDocument . Pri nt(Props()) ' une page par zone 
end if 
End Sub 

Les zones d'impression sont visibles avec le menu Format>Zones d'impression>Editer... 
La lecture de la propriete PrintAreas donne un tableau de coordonnees de zones 
d'impression. 



Repeter les en-tetes 

Le tableau 9-26 liste les proprietes de la feuille qui gouvernent l'impression des 
en-tetes sur les pages successives. Comme ce sont des proprietes de feuille, on ne doit 
alors imprimer qu'une seule zone dans la feuille. 

Tableau 9-26 Options d'impression 



Pri ntTi tl eCol umns 


Boolean 


True si I'en-tete des colonnes est imprime sur chaque page. 


TitleColumns 


Object 


Coordonnees de la zone d'en-tete des colonnes. 


Pri ntTi tl eRows 


Bool ean 


True si I'en-tete des lignes est imprime sur chaque page. 


TitleRows 


Object 


Coordonnees de la zone d'en-tete des lignes. 



Pour repeter l'impression de I'en-tete des colonnes, il suffit d'ajouter des instructions 
comme : 



maZone = maFeui 1 1 e . getCell RangeByName("B4 : E4") 
maFeui lie. TitleColumns = maZone . RangeAddress 
maFeui lie. Pri ntTi tleCol umns = True 



Les diagrammes 

La grande richesse des diagrammes est bien representee par l'interface utilisateur, 
tant par l'outil Auto Format de diagramme que par les multiples et parfois complexes 
possibilites de modifications manuelles. S'il est possible d'inserer par macro un dia- 
gramme dans une feuille de tableur, ajuster tous les parametres necessaires represente 
une tache considerable et peu productive. II est bien plus simple d'utiliser un docu- 
ment existant (ou un modele) dans lequel les diagrammes ont ete crees avec l'inter- 
face utilisateur. 
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Obtenir un diagramme existant 

Chaque feuille d'un document Calc peut contenir plusieurs diagrammes. La collec- 
tion des diagrammes d'une feuille est exposee par l'objet Charts inclus dans celle-ci. 
Chaque diagramme possede un nom, qui nest pas accessible a l'utilisateur, et un 
objet inclus, embeddedObject, qui contientles caracteristiques du diagramme en tant 
que dessin. 

Un diagramme est en effet un dessin. Or, chaque page de Calc contient une page de 
dessin, Drawpage, qui est la collection des dessins de la feuille. Chaque dessin possede 
un nom, modifiable par l'utilisateur : dans le cas d'un diagramme, le selectionner, 
faire un clic droit et choisir Nommer l'objet... Un dessin de diagramme supporte le ser- 
vice 0LE2shape et expose l'objet Model qui n'est autre que l'objet inclus deja vu. La 
figure 9-2 resume ces relations. 



Figure 9-2 

Les diagrammes dans Calc 



getBylndex 
getByName 



Feuille 



Charts 




II existe plusieurs moyens d'acceder a l'objet inclus. Si vous etes certain qu'il n'existe 
qu'un seul diagramme dans la feuille, cette instruction suffit : 

Dim monDiag As Object 

monDiag = maFeui 11 e . Charts(O) . EmbeddedObject 
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La collection Charts donne acces a un de ses diagrammes avec la methode 
getBylndex ; avec OOoBasic une simple indexation suffit. Le nombre de dia- 
grammes dans la collection est fourni par la propriete Count de l'objet Charts. 

Si la feuille peut comporter plusieurs diagrammes, il est risque de se fier a l'index, car 
le rang du diagramme depend de l'ordre de creation. On peut eventuellement 
explorer chaque diagramme en recherchant un nom significatif de titre ou sous-titre. 
Si vous connaissez le nom interne, l'objet est accessible ainsi : 

Dim monDiag As Object 

monDiag = maFeui lie. Charts .getByName("Nom_xxx") . embeddedObject 

En realite, il est peu probable que vous connaissiez le nom interne. En revanche, 
vous avez toute latitude de nommer chacun de vos diagrammes avec l'interface utili- 
sateur. Nous allons retrouver l'objet diagramme a partir de ce nom, grace a la routine 
utilitaire FindObjectByName decrite a l'annexe B. Le document de l'archive Zip tele- 
chargeable comporte un diagramme nomme CapaDD dans la feuille DiagLine. 

I rem Code09-08 . ods bibli : Diagrammes Modulel 
Option Explicit 

Sub RetrouverDiagrammeO 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 

Dim forme As Object, diagl As Object, diag2 As Object, x As Long 

monDocument = thi sComponent 

lesFeuilles = monDocument. Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Di agLi gne") 

forme = FindObjectByName(maFeuille.Drawpage, "CapaDD", 

"com . sun . star . drawi ng .0LE2Shape") 

if not IsNul 1 (forme) then 
diagl = forme. Model 

if diagl. supportsServi ce(" com. sun .star, chart .Char tDocument") then 
' diagl est bien le diagramme recherche. Verification : 
for x = 0 to maFeui lie. Charts. Count -1 ' balayer chaque diagramme 
diag2 = maFeuille. Charts(x) .EmbeddedObject 
if Equal UnoObjects (diagl, diag2) then 

MsgBox("Rang du diagramme dans la collection : " & x & chr(13) & _ 

"Nom du diagramme : " & maFeuille. Charts(x) .Name) 
Exit Sub ' diagramme retrouve 
end if 
next 
end if 
end if 

MsgBox("Le diagramme n'existe pas !", 16) 
End Sub 
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La fonction utilitaire Fi ndObjectByName est recopiee dans la bibliotheque Standard du 
document. Elle cherche, dans la page de dessin associee a la feuille Calc, une forme 
(dessin) ayant le nom CapaDD et supportant le service 0LE2Shape. Si un tel objet n'existe 
pas, elle renvoie la valeur Null. Ceci nest pas une condition suffisante : il pourrait s'agir 
d'un objet OLE qui ne serait pas un diagramme. Pour nous en assurer, nous recuperons 
le modele de cet objet et verifions qu'il supporte le service ChartDocument. 

Pour la demonstration, nous retrouvons le meme diagramme dans la collection 
Charts de la feuille grace a la fonction Basic Equal UnoObjects qui renvoie True si les 
deux variables designent le meme objet. Finalement, le rang du diagramme trouve et 
son nom interne sont affiches. Dans tous les autres cas, le diagramme n'est pas 
retrouve, done un message d'erreur est affiche. 

Les proprietes d'un diagramme 

Le tableau 9-27 liste les principales proprietes de 1' objet inclus, que nous designerons 
par monDi ag dans l'exemple qui suit. 

Tableau 9-27 Proprietes de I'objet inclus dans un diagramme 



HasMai nTitle 


Boolean 


True si un titre est utilise. 


Title 


Object 


Titre du diagramme (objet Forme). 


HasSubTitle 


Bool ean 


True si un sous-titre est utilise. 


SubTitle 


Object 


Sous-titre du diagramme. 


HasLegend 


Boolean 


True si la legende est affichee. 


Legend 


Object 


Legende du diagramme. 


Area 


Object 


Arriere-plan du diagramme. 


Di ag ram 


Object 


Le dessin du diagramme. 



Chacun de ces objets possede de multiples proprietes ou objets, que nous n'allons pas 
developper ici car elles sont reglables directement avec l'interface utilisateur. 



Attention 

Certaines caracteristiques - comme les dimensions de la legende - sont calculees automatiquement par 
OpenOffice.org en fonction du contenu. N'esperez pas les modifier via I'API. 



Si vous souhaitez etudier ce sujet, utilisez l'outil Xray (voir l'annexe A) pour analyser 
les proprietes et methodes de monDi ag et afficher la documentation de chaque objet. 
Continuez l'analyse sur les sous-objets. A titre d'exemple, nous allons affecter au titre 
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d'un diagramme le texte de la cellule Al de la meme feuille et changer la couleur des 
caracteres. Le codage suppose qu'il n'y a qu'un seul diagramme dans la feuille Calc. 

rem Code09-08 . ods bibli : Diagrammes Module2 
Option Explicit 

Sub ChangerTitreDiagrammeO 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 

Dim diagl As Object, maCellule As Object 

monDocument = thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Di agLi gne") 

' on suppose que la feuille comporte un seul diagramme ! 

diagl = maFeuille.Charts(O) . EmbeddedObject 

diagl.Title.CharColor = RGB(120, 0, 0) ' changer la couleur 

maCellule = maFeuille.getCellRangeByName("Al") 

diagl. Title. String = maCel 1 ul e . Stri ng ' changer le titre 

End Sub 



Changer la zone de donnees d'un diagramme 

La zone de donnees utilisee par un diagramme est memorisee dans un des elements 
du conteneur Charts de la feuille. Ici aussi nous supposons que la feuille ne comporte 
qu'un seul diagramme. 

rem Code09-08 . ods bibli : Diagrammes Module3 
Option Explicit 

Sub ChangerZoneDonnees 

Dim monDocument As Object, lesFeuilles As Object, maFeuille As Object 
Dim ch As Object, lesZones As Variant, adrZ As Object 
monDocument = thi sComponent 
I lesFeuilles = monDocument. Sheets 
maFeuille = 1 esFeui 1 1 es . getByName("Di agLi gne") 
' on suppose que la feuille comporte un seul diagramme ! 
ch = maFeuille.Charts(O) 
lesZones = ch. Ranges 

adrZ = lesZones(O) ' dans cet exemple on a une seule zone 
adrZ.EndRow = 9 1 redui re la zone a A2:B10 
lesZones(O) = adrZ 
ch. Ranges = lesZones () 
End Sub 

La propriete Ranges du diagramme nous donne un tableau de structures 
Cell RangeAddress qui correspond aux zones de cellules servant de donnees. Dans 
notre cas, le diagramme n'utilise qu'une seule zone, A2 : B12 (elle comprend les en- 
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tetes). Nous reduirons la zone de deux lignes en modifiant la valeur de EndRow pour la 
zone de cellules. L'ensemble du tableau doit etre ensuite recrit dans la propriete Ranges. 



Les styles 

Nous avons indique au chapitre 7 les elements communs a la gestion des styles. Nous 
abordons maintenant les styles propres aux documents Calc. 

Style de cellule 

Dans le style de cellule, nous retrouvons : 

• les proprietes globales de la cellule, 

• les proprietes de formatage local de la cellule. 
Ces proprietes ont ete decrites precedemment. 



Style de page 



Les proprietes de style de page comprennent, outre celles du tableau 9-28, des proprietes 
relatives a l'en-tete et au bas de page, qui sont decrites dans une section particuliere. 

Tableau 9-28 Proprietes de style de page 



BackColor 


Long 


Couleur du fond (visible avec I'apercu). 


BackTransparent 


Bool ean 


True rend le fond transparent (interface utilisateur : sans remplissage). 


TopBorder 


Object 


Structure de la ligne de bordure du haut. Voir tableau 9-1 0. 


TopBorderDi stance 


Long 


Espacement par rapport a la bordure du haut. 


BottomBorder Object Structure de la ligne de bordure du bas. Voir tableau 9-10. 


BottomBorderDi stance 


Long 


Espacement par rapport a la bordure du bas. 


LeftBorder 


Object 


Structure de la ligne de bordure de gauche. Voir tableau 9-10. 


LeftBorderDi stance 


Long 


Espacement par rapport a la bordure de gauche. 


RightBorder 


Object 


Structure de la ligne de bordure de droite. Voir tableau 9-10. 


Ri ghtBorderDi stance 


Long 


Espacement par rapport a la bordure de droite. 


Shadow/Format 


Ob j ect Ombre portee. Voir tableau 9-7. 


TopMargi n 


Long 


Marge du haut, en 1/100 de mm. 


BottomMargi n 


Long 


Marge du bas, en 1/100 de mm. 


LeftMargi n 


Long 


Marge de gauche, en 1/100 de mm. 
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Tableau 9-28 Proprietes de style de page (suite) 



Ri ghtMargi n 


Long Marge de droite, en 1/100 de mm. 


IsLandscape 


Bool ean 


True si la page est en orientation Paysage. 


Numberi ngType 


Integer 


Type de numerotation par defaut. Constante nommee, voir tableau 9-30. 
Valeur par defaut : 

com. sun . star . styl e . Numberi ngType .ARABIC 


PageStyl eLayout 


Integer 


Indique quelles pages sont concernees. Constante nommee, voir 

tableau 9-29. Valeur par defaut : 

com. sun . star . styl e . PageStyl eLayout . ALL 


Pri nterPaperTray 


Stri ng 


Norn du bac de I'imprimante selectionnee. 


Width 


Long 


Hauteur de la page, en 1 /1 00 de mm. 


Height 


Long 


Largeur de la page, en 1/100 de mm. 


Center-Horizontally 


Boolean 


True pour aligner la table horizontalement. 


CenterVerti cal 1 y 


Bool ean True pour aligner la table verticalement. 


Fi rstPageNumber 


Integer 


Numero de la premiere page d'impression pour cette feuille. Si la valeur 
vaut zero, la numerotation suit celle de la feuille precedente. 


PageScale 


Integer 


Echelle de reduction (en pourcentage) pour imprimer la zone d'impression. 


Seal eToPages 


Integer 


Nombre de pages pour imprimer toute la zone d'impression. 


Seal eToPagesX 


Integer Nombre de pages pour imprimer la largeur de la zone d'impression. 


ScaleToPagesY 


Integer 


Nombre de pages pour imprimer la hauteur de la zone d'impression. 


Pri ntAnnotations 


Boolean 


True pour imprimer les notes de cellules. 


Pri ntCharts 


Boolean 


True pour imprimer les diagrammes. 


Pri ntDownFi rst 


Boolean 


True pour imprimer de haut en bas, puis les colonnes suivantes sur la droite. 
Fal se pour imprimer de gauche a droite, puis les lignes suivantes en des- 
sous. 


Pri ntDrawi ng 


Boolean 


True pour imprimer les dessins 


Pri ntFormul as 


Boolean 


True pour imprimer le texte des formules. 
Fal se pour imprimer le resultat des formules. 


PrintCrid 


Boolean 


True pour imprimer la grille des cellules. 


PrintHeaders 


Boolean 


True pour imprimer les en-tetes de ligne et colonnes. 


Pri ntObjects 


Boolean 


True pour imprimer les objets incorpores. 


Pri ntZeroVal ues 


Boolean 


True pour imprimer les valeurs nulles. 
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Tableau 9-29 Constantes de disposition de page 



ALL Pages gauches et droites. 


LEFT 


Pages gauches seulement. 


RIGHT 


Pages droites seulement. 


MIRRORED 


Les pages gauches utilisent ce style, les pages droites prennent des 
valeurs en miroir. 


Tableau 9-30 Constantes de type de numerotation 




ARABIC 


1,2, 3,4 


CHARS_UPPER_LETTER 


A, B, C, D 


CHARS_LOWER_LETTER 


a, b, c, d 


ROMANLUPPER 


I, II, III, IV, V 


R0MAN_L0WER 


i, ii, iii, iv, V 


NUMBER_N0NE 


Pas de numerotation. 


CHARS_UPPER_LETTER_N 


A, B, Y, Z, AA, BB, CC, ... AAA, ... 


CHARS_LOWER_LETTER_N 


a, b, y, z, aa, bb, cc, ... aaa, ... 



Comment utiliser les styles de page 

Pour inserer dans un document des pages d'orientation differente ou ayant d'autres 
caracteristiques particulieres, il est recommande d'utiliser des styles de page appropries. 
Tous les styles de page sont bases sur le style Standard. Nous allons creer deux styles : 

• un style a orientation Portrait au format A4, qui est simplement une copie du 
style Standard ; 

• un style a orientation Paysage, lui aussi au format A4. 

La macro va creer les deux styles successivement. Dans le panneau Styles et formatage, 
basculez eventuellement l'affichage d'une famille de styles a l'autre pour faire appa- 
raitre les nouveaux styles. 



rem Code09-07 . ods 
Option Explicit 



bibli : OrientationPages Modulel 



Sub CreerDeuxStylesPageO 
Dim monDocument As Object 

Dim lesFamilles As Object, uneFamille As Object 
Dim nouvStyle As Object 
monDocument = Thi sComponent 
lesFamilles = monDocument. Sty! eFami "lies 
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uneFamille = lesFamilles.getByName("PageStyles") 
nouvStyle = monDocument.CreateInstance(_ 

"com . sun . star . styl e . PageStyl e") 
' creer un nouveau style identique au style Standard 
uneFamille. "insertByName ("A4 Portrait", nouvStyle) 
nouvStyle.BackColor = RCB(230 , 230 , 255) 
nouvStyle = monDocument.CreateInstance(_ 

"com . sun . star . styl e . PageStyl e") 

' creer un style Paysage 

uneFamille. insertByName ("A4 Paysage", nouvStyle) 

nouvStyl e . IsLandscape = True 
nouvStyle. Width = 29700 ' hauteur 29,7 cm 
nouvStyle. Height = 21000 ' largeur 21,0 cm 
End Sub 

Pour chaque nouveau style, nous obtenons un objet style avec la fonction 
Createlnstance de 1' objet document. Ce style est insere dans sa famille par la 
methode insertByName puis eventuellement modifie. Remarquez qu'avec le format 
Paysage, nous avons aussi change la hauteur et la largeur, alors qu'avec l'interface uti- 
lisateur un simple clic sur le bouton Paysage suffit a intervertir ces deux valeurs. 

Nous disposons maintenant de deux nouveaux styles, A4 Portrait et A4 Paysage. 
Nous allons les utiliser dans la macro suivante, qui va affecter le premier a une feuille, 
le deuxieme a une autre feuille. 

rem Code09-07.ods bibli : Ori entati onPages Module2 
Option Explicit 

1 executez auparavant la routine du module 1 
Sub ChangerStyleFeuille() 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("Feui 11 e3") 

maFeuille. PageStyl e = "A4 Portrait" 

maFeuille = 1 esFeui 1 1 es . getByName("Feui 11 e4") 

maFeuille. PageStyl e = "A4 Paysage" 

End Sub 

Sur le document modifie, vous pouvez facilement verifier le style de page de la feuille 
visible : il est affiche en bas de la fenetre Calc. Cliquez sur l'icone Apercu et visualisez 
successivement les pages imprimees : vous observerez le fond bleu clair sur la zone affi- 
chee de la feuille 3 et le changement d'orientation pour la page contenant la feuille 4. 
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Les en-tetes et pieds de page 

Les en-tetes et pieds de page ne sont pas des elements ordinaires du document. En 
effet, ils sont des elements appartenant a un style de page, par defaut le style de page 
Standard. Pour faire apparaitre ou pour modifier un en-tete ou un pied de page, il 
faut connaitre ou retrouver le style de page de la feuille qui nous interesse et le modi- 
fier. En consequence, toutes les feuilles du meme style subiront la meme modifica- 
tion d'en-tete ou de pied de page. 

Nous allons inserer un en-tete dans les pages d'impression de la feuille 4. Notre 
en-tete n'est pas differencie entre pages gauches et pages droites, il suffit de remplir 
celui des pages de droite. 

rem Code09-07 . ods bibli : Haut_Bas Modulel 
Option Explicit 

Sub InsererUnEnTeteO 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, enTete As Object 

Dim Texte2 As Object, Curseur2 As Object 

Dim nomStyl eMaPage As String, Styl eMaPage As Object 

Dim stylesPage As Object 

monDocument = Thi sComponent 

lesFeuilles = monDocument . Sheets 

maFeuille = lesFeuilles. getByName("Feuille4") 

' recuperer le nom du style de page en cours 

nomStyl eMaPage = maFeuille.PageStyle 

print "Cette page est du style : " & nomStyl eMaPage 

' recuperer la collection de styles de pages 

styl esPage = monDocument . Styl eFami 1 i es . getByName ("PageStyl es") 
' recuperer le style de page 

Styl eMaPage = stylesPage. getByName (nomStyl eMaPage) 
Styl eMaPage . HeaderlsOn = true 1 inserer un en-tete 
Styl eMaPage. HeaderBodyDi stance = 1000 ' 10 mm 
StyleMaPage.HeaderHeight = 2500 ' 25mm 

' 1 'en-tete page droite est aussi utilise pour la gauche 
enTete = Styl eMaPage. RightPageHeaderContent 
Texte2 = enTete. LeftText ' zone de texte gauche de 1 'en-tete 
Curseur2 = Texte2 . createTextCursor ' curseur dans 1 'en-tete 
' ecrire un texte dans 1' en-tete 

Texte2 . i nsertStri ng(Curseur2 , "Voici un en-tete", false) 
Styl eMaPage. RightPageHeaderContent = enTete' mettre a jour 
End Sub 
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Une fois recupere le style de page, nous activons l'en-tete, regions sa hauteur et sa 
position, et obtenons le contenu de l'en-tete. II comporte trois zones de texte : 
gauche, centre, droit. Nous recuperons l'objet texte de la partie gauche. La phase 
d'ecriture utilise toutes les possibilites d'ecriture dans un texte Writer. De meme, 
nous pourrions modifier les deux autres zones. Enfin, nous recopions le nouveau 
contenu dans l'en-tete du style de page. 

Nous voyons encore un exemple ou l'usage d'un document modele avec des styles 
bien definis peut alleger considerablement l'ecriture de macros en evitant de creer ou 
modifier les en-tetes ou has de page. 

L'objet style de page expose un tres grand nombre de proprietes pour l'en-tete (Header) 
et pour le pied de page (Footer). Comme ces proprietes sont similaires, le tableau 9-31 
ne listera que les principales proprietes de l'en-tete, sachant qu'il suffit de remplacer 
Header par Footer dans le nom de propriete pour obtenir celle du bas de page. 

Tableau 9-31 Principales proprietes d'en-tete de page 



HeaderlsOn 


Boolean 


True si un en-tete est active. 


HeaderlsShared 


Boolean 


True si les en-tetes gauche et droite sont identiques (valeur par 
defaut). 


HeaderBackColor 


Long 


Couleur du fond. 


HeaderBackTran spa rent 


Boolean 


True rend le fond transparent (interface utilisateur : sans remplis- 
sage). 


HeaderLeftBorderDi stance 


Long 


Distance entre marge et bord gauche de l'en-tete, en 1/100 de mm. 


HeaderRi ghtBorderDi stance 


Long 


Distance entre marge et bord droit de l'en-tete, en 1/100 de mm. 


HeaderTopBorderDi stance 


Long 


Distance entre marge et bord du haut de l'en-tete, en 1/1 00 de mm. 


HeaderBottomBorderDi stance 


Long 


Distance entre marge et bord du bas de l'en-tete, en 1/100 de mm. 


HeaderBodyDi stance 


Long 


Distance entre en-tete et texte principal, en 1/100 de mm. 


HeaderHei ght 


Long 


Hauteur de l'en-tete, en 1/100 de mm. 


HeaderShadowFormat 


Object 


Ombre port.ee. Voir tableau 9-7. 


Ri ghtPageHeaderContent 


Object 


Structure d'acces au texte de l'en-tete des pages droites, ou de tou- 
tes les pages, voir tableau 9-32. 


Left PageHeaderCon tent 


Object 


Structure d'acces au texte de l'en-tete des pages gauches, voir 
tableau 9-32. 


HeaderLeftMargi n 


Long 


Marge gauche de l'en-tete. 


HeaderRi ghtMargi n 


Long 


Marge droite de l'en-tete. 


HeaderLeftBorder 


Object 


Structure de la ligne de bordure de gauche. Voir bordure de cellule. 


HeaderRi ghtBorder 


Object 


Structure de la ligne de bordure de droite. Voir bordure de cellule. 
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Tableau 9-31 Principales proprietes d'en-tete de page (suite) 



HeaderTopBorder 


Object 


Structure de la ligne de bordure du haut. Voir bordure de cellule. 


HeaderBottomBorder 


Object 


Structure de la ligne de bordure du bas. Voir bordure de cellule. 


Tableau 9-32 Structure d'un contenu d'en-tete de page 




LeftText 


Object 


Zone gauche du texte de I'en-tete. 


Center-Text 


Object 


Zone centrale du texte de I'en-tete. 


RightText 


Object 


Zone droite du texte de I'en-tete. 



Les formes et les images 

Nous expliquerons ici les particularites de Calc concernant les figures de dessin (formes) 
et les images. Dans le chapitre consacre a Draw, nous decrivons en detail les differents 
types de formes, leurs proprietes, leur manipulation, ainsi que les proprietes des images. 
Vous y trouverez aussi des explications sur d'autres types d'objets inseres dans une page 
de dessin, qui s'appliquent egalement a la page de dessin d'une feuille Calc. 

La page de dessin 

Chaque feuille d'un document Calc dispose d'une page de dessin. L'objet page est 
accessible de deux manieres : soit a partir du conteneur DrawPages du document 
Calc, soit a partir de la propriete DrawPage de la feuille. Attention a l'orthographe ! 
Une page du conteneur DrawPages nest accessible que par le rang de la feuille dans le 
document (methode getBylndex, ou indexage direct en Basic) ; ce nest done pas 
bien pratique, autant obtenir la page a partir de la feuille. 

Dim maPage As Object 

maPage = monDocument . DrawPages(x) ' methode 1 
maPage = maFeui 1 1 e . DrawPage ' methode 2 

Cette page de dessin dans Calc ne comporte pas les proprietes d'une page Draw, 
mais uniquement la liste des objets sur cette page. Elle possede quatre couches, non 
documentees, qui ne sont pas accessibles directement par l'API ; elles sont enume- 
rees au tableau 9-33. Une forme, ainsi qu'une image, comporte deux proprietes : 
Layerld, le numero de couche, et LayerName, le nom de la couche ou se trouve la 
forme. On peut deplacer la forme sur une autre couche en modifiant Layerld. 
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Tableau 9-33 Couches de la page de dessin 



0 


vorne 


Couche visible, en avant-plan. Apres son insertion, la forme ou I'image se trouve 
dans cette couche. 


1 


hi nten 


Couche visible, en arriere-plan, derriere les cellules. L'utilisateur ne peut selec- 
tionner la forme directement, il doit I'encadrer avec I'outil selection (fleche). 


2 


i ntern 


Couche visible, devant les cellules. L'utilisateur ne peut plus selectionner la forme. 


3 


Controls 


Couche visible, utilisee par les controles de formulaire. 



Les formes 

Une forme ou une image est ancree soit « a la cellule », soit « a la page ». L'insertion 
se fait toujours « a la cellule ». Le seul moyen de changer l'ancrage par programma- 
tion est d'utiliser le dispatcher (de l'enregistreur de macros) avec la commande 
" . uno : SetAnchorToPage" apres avoir selectionne la forme. 



Inserer une forme 

L'insertion d'une forme sur la page de dessin de la feuille se fait en utilisant la pro- 
priete add de la page de dessin. La forme sera ancree « a la cellule ». 

rem Code09-ll.ods bibli : Dessins Modulel 
Option Explicit 

Sub AjouterEl 1 i pse() 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maPage As Object, maForme As Object 

Dim dimensionsForme As New com. sun. star. awt. Size 

Dim positionForme As New com. sun . star . awt . Poi nt 

monDocument = thi sComponent 

lesFeuilles = monDocument. Sheets 

maFeuille = 1 esFeui 1 1 es . getByName("F01") 

maPage = maFeuille.DrawPage ' recuperer la page de dessin 

dimensionsForme. Width = 2600 ' 26 mm de largeur 

dimensionsForme. Height = 1200 ' 12 mm de hauteur 

positionForme. x = 3500 1 35 mm a droite du coin de la feuille 

positionForme. y = 3300 ' 33 mm en dessous du coin de la feuille 



maForme = monDocument . createlnstance(" com. sun . star .drawi ng . Ell ipseShape") 

maForme. Size = dimensionsForme 

maPage. add (maForme) 

maForme . Position = positionForme 

maForme. Name = "Ovale" ' donner un nom a cette forme 
End Sub 
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Si vous selectionnez manuellement la forme obtenue sur la feuille, vous verrez quelle 
est ancree a une cellule de la feuille, par exemple B8. L'API a choisi comme cellule 
d'ancrage celle qui englobe le point de positionnement, et a complete le positionne- 
ment de la forme par rapport a cette cellule pour obtenir la position voulue. Effacez 
la forme ; modifiez la largeur de la colonne A et la hauteur d'une des premieres 
lignes ; re-executez la macro : le choix de la cellule d'ancrage changera. Ceci signifie 
que le positionnement est toujours calcule par rapport a la page et converti en posi- 
tionnement a la cellule. Si, apres insertion de la forme, on modifie la largeur d'une 
colonne ou la hauteur d'une ligne recouverte par la forme, ses dimensions change- 
ront. Si on modifie la largeur d'une colonne precedente ou la hauteur d'une ligne 
precedente, la position de la forme changera. 

La propriete Anchor, en lecture seule, renvoie un objet qui est soit la cellule soit la 
feuille Calc d'ancrage de la forme ou de l'image. 



BOGUE Position et dimensions d'une forme 

Si vous changez par programme la position ou les dimensions d'une forme existante, le document ne 
passe pas a I'etat « modifie ». Vous pouvez cependant forcer cet etat, voir le chapitre 7. 



Inserer plusieurs formes 

A chaque insertion d'une forme, il est necessaire d'obtenir un nouvel objet forme, 
meme si on insere plusieurs fois le meme type de forme. II faut aussi reinitialiser a 
chaque fois les proprietes de la forme. Dans cet exemple, on insere deux rectangles 
identiques a la meme position, ancres sur deux feuilles differentes du document Calc. 
Nous leur donnons un nom, qui nous servira dans le prochain exemple. 

rem Code09-ll . ods bibli : Dessins Module2 
Option Explicit 

Sub PlusieursFormesO 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maPage As Object, maForme As Object 

Dim dimensionsForme As New com. sun. star. awt. Size 

Dim position Forme As New com. sun. star. awt. Point 

monDocument = thisComponent 

lesFeuilles = monDocument. Sheets 

dimensionsForme. Width = 5500 ' 55 mm de largeur 

dimensionsForme. Height = 1200 ' 12 mm de hauteur 

positionForme.x = 3500 ' 35 mm a droite du coin de la feuille 

positionForme.y = 7200 ' 72 mm en dessous du coin de la feuille 

' premiere forme inseree sur la feuille F01 

maFeuille = lesFeuilles. getByName("F01") 

maPage = maFeuille.DrawPage ' recuperer la page de dessin 
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maForme = monDocument . createInstance("com . sun . star . drawn ng . Rectangl eShape") 

maForme.Size = dimensionsForme 

maPage . add (maFo rme) 

maForme. Position = positionForme 

maFo rme. Name = "Recti" ' donner un nom a cette forme 

' deuxieme forme inseree sur la feuille F02 

maFeuille = lesFeuilles.getByName("F02") 

maPage = maFeuille.DrawPage ' recuperer la page de dessin 

maForme = monDocument . createInstance("com . sun . star . drawi ng . Rectangl eShape") 

maForme.Size = dimensionsForme 

maPage . add (maFo rme) 

maForme. Position = positionForme 

maForme. Name = "Rect2" ' donner un nom a cette forme 
End Sub 

Retrouver et supprimer une forme 

Le Navigateur de Calc nest pas capable de lister les objets dessins d'un document. 
Neanmoins, avec une macro, nous sommes capables de retrouver une forme nommee 
sur la page de dessin d'une feuille. Nous emploierons a cet effet la routine utilitaire 
Fi ndObjectByName decrite a l'annexe B. Elle est recopiee dans la bibliotheque 
Standard du document exemple. 

rem Code09-ll.ods bibli : Dessins Module3 
Option Explicit 

Sub Sel ecti onnerForme() 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maPage As Object, maForme As Object 

monDocument = thi sComponent 

lesFeuilles = monDocument. Sheets 

maFeuille = lesFeuilles. getByName("F01") 

maPage = maFeuille.DrawPage ' recuperer la page de dessin 

maForme = Fi ndObjectByName (maPage , "Recti") 

if IsNul 1 (maForme) then 

print "II n'existe aucune forme de ce nom" 
el se 

monDocument . Cur rentControl 1 er . Sel ect (maForme) 
end if 
End Sub 

Une fois la forme trouvee, nous pouvons la modifier. Ici on se contente de la selectionner 
de maniere visible en employant la methode sel ect du controleur du document. 

La suppression d'une forme s'effectue a partir de la page de dessin, par sa methode 
remove. 

maPage. remove(maForme) 
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Les images 

Les principes d'insertion, recuperation et suppression d'une image sont similaires a 
ce que nous avons vu pour les formes. 

Inserer une image 

L'insertion d'une image sur la page de dessin se fait en utilisant la propriete add de la 
page de dessin. 

rem Code09-ll.ods bibli : leslmages Modulel 
Option Explicit 

Sub AjouterlmageO 

Dim monDocument As Object, lesFeuilles As Object 

Dim maFeuille As Object, maPage As Object, monlmage As Object 

Dim positionlmage As New com. sun. star. awt. Point 

monDocument = thisComponent 

lesFeuilles = monDocument. Sheets 

maFeuille = lesFeuilles. getByName("F01") 

maPage = maFeuille.DrawPage ' recuperer la page de dessin 

positionlmage. x = 3500 ' 35 mm a droite du coin de la feuille 

positionlmage. y = 3300 ' 33 mm en dessous du coin de la feuille 

monImage=monDocument.createInstance("com. sun. star. drawi ng .GraphicObjectShape") 
monlmage. GraphicURL = ConvertToURL("C:\Docs 0pen0ffice\Logo0pen0ffice.png") 
maPage. add (monlmage) 

resizelmageByWidth (monlmage, 5500) ' largeur en 1/100 de mm 
monlmage. Position = positionlmage 
monlmage. Name = "Logo2" ' donner un nom a cette image 
End Sub 

Pour dimensionner l'image sur le document en conservant les proportions de l'image, 
nous utilisons la routine utilitaire resizelmageByWidth, que nous avons extraite de 
l'annexe B de ce livre. Cette routine est recopiee dans la bibliotheque Standard du 
document exemple. 

Inserer plusieurs images 

A chaque insertion d'une image, il est necessaire d'obtenir un nouvel objet image, 
meme si on insere plusieurs fois la meme. II faut aussi reinitialiser a chaque fois les 
proprietes de la forme. Le document Codel2-ll.odt de 1' archive Zip telechargeable 
contient un exemple. 
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Retrouver et supprimer une image 

La methode et le codage exposes pour les formes s' applique aussi bien a une image 
qu'on a nommee. 



Configuration du document 

Un document Calc possede quelques proprietes de configuration interessantes, 
comme le montre le tableau 9-34. Elles reprennent les options de l'interface utilisa- 
teur Outils>0ptions>0pen0ffice.org CaloCalcul, mais ne s'appliquent qu'au document 
traite. Pour les proprietes de type Bool ean, la valeur True correspond a la case cochee 
dans l'interface utilisateur. 

Tableau 9-34 Proprietes de calcul pour un document Calc 



Propriete 


Type 


Equivalence dans l'interface utilisateur 


Islte rati on Enabled 


Bool ean 


References circulaires, case Iterations. 


IterationCount 


Long 


References circulaires, valeur de Pas. 


IterationEpsilon 


Double 


References circulaires, valeur de changement minimum. 


IgnoreCase 


Boolean 


Respecter la casse. 


MatchWholeCell 


Boolean 


Criteres de recherche = et <> doivent correspondre a des cel- 
lules entieres. 


CalcAsShown 


Boolean 


Exactitude comme affiche. 


LookUpLabel s 


Boolean 


Rechercher automatiquement les etiquettes de colonnes et 
lignes. 


Regular Expressions 


Boolean 


Autoriser les caracteres generiques dans les formules. 



Un petit exemple : 



monDocument. LookUpLabel s = False 

Configuration d'affichage du document 

Ces proprietes du document Calc (tableau 9-35), qui existent dans l'interface utilisa- 
teur principalement au niveau Outils>Options>Classeur>Affichage, sont accessibles a 
partir de l'objet controleur du document. Elles sont, pour certaines, memorisees a la 
sauvegarde du document. Pour les proprietes de type Boolean, la valeur True corres- 
pond a la case cochee dans l'interface utilisateur (sauf exception). La modification du 
zoom impacte toutes les feuilles du document. 
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rem Code09-06 . ods bibli : Config Modulel 
Option Explicit 

Sub ConfigDocCalcO 

Dim monDocument As Object, leControleur As Object 
monDocument = Thi sComponent 

' voir des valeurs pour exemple dans la feuille 2 

leControleur = monDocument . CurrentControl 1 er 

With leControleur 

. ShowZeroVal ues = MsgBox("ShowZeroVal ues ?", 4) = 6 

.ShowNotes = MsgBox("ShowNotes ?", 4) = 6 

.ShowCrid = MsgBox("ShowCri d ?", 4) = 6 

. ShowPageBreaks = MsgBox("ShowPageBreaks ?", 4) = 6 

. HasCol umnRowHeaders = MsgBox("HasCol umnRowHeaders ?", 4) = 6 

.ShowFormulas = MsgBox("ShowFormul as ?", 4) = 6 

end With 

End Sub 



Tableau 9-35 Proprietes d'affichage de Calc 



Propriete 


Type 


Equivalence dans I'interface utilisateur 


ShowZeroVal ues 


Bool ean 


Afficher>Valeurs zero 


ShowAnchor 


Bool ean 


Afficher>Ancre 


ShowFormul as 


Boolean 


Afficher>Formules 


ShowNotes 


Boolean 


Afficher>lndicateur de notes 


IsVal ueHi ghl i ghti ngEnabl ed 


Boolean 


Afficher>Mise en evidence des valeurs 


ShowPageBreaks 


Bool ean 


Aides visuelles>Sauts de page 


ShowHel pLi nes 


Bool ean 


Aides visuelles>Reperes du deplacement 


ShowCri d 


Bool ean 


Aides visuelles>Lignes de la grille 


GridColor 


Long 


Aides visuelles>Couleur du trait de la grille 


SolidHandles 


Boolean 


Aides visuelles>Poignees simples 

La valeur Fal se correspond a I'etat coche ! 


HasVerti cal Scrol 1 Bar 


Bool ean 


Fenetre>Barre de defilement verticale 


HasHori zontal Scrol 1 Bar 


Boolean 


Fenetre>Barre de defilement horizontale 


HasSheetTabs 


Boolean 


Fenetre>Onglets des feuilles 


IsOutl i neSymbol sSet 


Boolean 


Fenetre>Symboles du plan 


HasCol umnRowHeaders 


Boolean 


Fenetre>En-tetes de lignes et colonnes 


ShowObjects 


Integer 


Objets>Objets/lmages 

Valeur : 0 pour afficher, 1 pour masquer. 


ShowCharts 


Integer 


Objets>Diagrammes 

Valeur : 0 pour afficher, 1 pour masquer. 
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Tableau 9-35 Proprietes d'affichage de Calc (suite) 
Equivalence dans I'ir 



ShowDrawi ng 


Integer 


Objets>Objets de dessin 

Valeur : 0 pour afficher, 1 pour masquer. 


Hi deSpell Marks 


Boolean 


True pour cacher les marques du correcteur d'orthographe. 


ZoomType 


Integer 


Menu Affichage>Zoom>Facteur de zoom>(choix) 
Constante nommee, voir chapitre 7. 


ZoomValue 


Integer 


Menu Affichage>Zoom>Facteur de zoom>Autre 
Valeur du zoom : voir chapitre 7. 
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Nous decrivons ici comment modifier certaines options de l'application Calc. Elles s'appli- 
quent ensuite a chaque ouverture de document Calc. Neanmoins, vous pouvez aussi modi- 
fier ces proprietes temporairement, pendant un travail sur un document particulier. 

Le service Global SheetSettings donne acces a plusieurs proprietes interessantes, 
listees dans le tableau 9-36. Elles ont pour la plupart un equivalent dans le panneau 
du menu Outils>Options>Classeur. Elles sont accessibles en lecture et en ecriture. La 
mise en ceuvre est tres simple, par exemple : 

Dim sv As Object 

sv = CreateUnoServi ce("com . sun . star . sheet .Global SheetSetti ngs") 
sv.MoveSelection = false 

Tableau 9-36 Principales proprietes de GlobalSheetSettings 



MoveSel ecti on 


Boolean 


True pour deplacer la selection de cellule quand on appuie 

sur la touche Entree. 

Fal se pour rester sur la meme cellule. 


MoveDi recti on 


Integer 


Sens du deplacement du curseur de cellule a I'appui de la 
touche Entree (si la propriete MoveSel ecti on vaut 
True). Constante nommee, voir tableau 9-37. 


UseTabCol 


Boolean 


Avec la valeur True, et si MoveSel ecti on vaut True, a 
I'appui de la touche Entree la selection de cellule revient 
dans la colonne d'ou on etait parti avec une tabulation. Le 
deplacement est aussi combine avec la valeur de 
MoveDi recti on. 


EnterEdit 


Boolean 


True bascule en mode edition quand on appuie sur la tou- 
che Entree. 
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Tableau 9-36 Principales proprietes de GlobalSheetSettings (suite) 



ExtendFormat 


Bool ean 


True active I'expansion du formatage. 


RangeFi nder 


Boolean 


True affiche les references en couleur. 


ExpandReferences 


Boolean 


True active I'expansion des references. 


MarkHeader 


Boolean 


True met en evidence la selection dans les en-tetes de 
lignes et colonnes. 


DoAutoCompl ete 


Bool ean 


True pour activer I'AutoSaisie. 


StatusBarFunction 


Intege r 


Fonction utilisee dans la barre d'etat (voir explications). 


Scale 


Integer 


Valeur par defaut du zoom sur un nouveau document Calc, 

s'il n'est pas base sur un modele. 

La valeur est en pourcentage, 100 pour 100 %, ou bien : 

-1 pour un zoom optimal, 

-2 pour afficher la page entiere, 

-3 pour s'adapter a la largeur de page. 


UserLi sts 


Array(Str 
ing) 


Listes de tri. Chaque liste est une chame de caracteres dont 
chaque nom est separe du suivant par une virgule. 


LinkUpdateMode 


Integer 


Actualiser les liens au chargement : 
0 : toujours, 

1 : jamais, 

2 : sur demande. 


PrintAll Sheets 


Boolean 


True pour imprimer toutes les feuilles. 

Fal se pour n'imprimer que les feuilles selectionnees. 


Pri ntEmptyPages 


Bool ean 


True pour imprimer meme les feuilles vides. 


UsePri nterMetri cs 


Boolean 


True pour utiliser les parametres de I'imprimante pour le 
formatage. 


Repl aceCel 1 sWarni ng 


Boolean 


True pour avertir avant d'ecraser la donnee d'une cellule. 



Les constantes pour MoveDi recti on, listees au tableau 9-37, sont de la forme : 
com . sun . star . sheet . MoveDi recti on . RIGHT 

Tableau 9-37 Constantes de deplacement de selection 



DOWN 


Vers le bas. 


UP 


Vers le haut. 


RIGHT 


Vers la droite. 


LEFT 


Vers la gauche. 
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La propriete StatusBarFunction merite quelques explications. Lorsque vous selec- 
tionnez un groupe de cellules dans Calc, vous voyez en bas a droite de la fenetre Calc 
une indication comme : Somme=1234, 56. Automatiquement, Calc a applique une 
fonction a l'ensemble des cellules de la selection. Cette fonction est par defaut la 
somme des valeurs. En modifiant la propriete StatusBarFunction, vous pouvez 
choisir une autre fonction parmi celles listees au tableau 9-38. Les valeurs sont des 
constantes nominees de la forme : 

com . sun . star . sheet . StatusBarFuncti on . AVERAGE 
La figure 9-3 montre l'affichage d'une moyenne dans le tableur. 



Figure 9-3 

Moyenne automatique 




I 



Tableau 9-38 Constantes de fonction de barre d'etat 



NONE 


Pas de fonction. 


AVERAGE 


Moyenne des valeurs des cellules a contenu numerique. 


COUNTNUMS 


Nombre de cellules a contenu numerique (l'affichage est : Nombre=n). 


COUNT 


Nombre de cellules non vides (l'affichage est : Nombre2=n). 


MAX 


Valeur maximale des cellules a contenu numerique. 


MIN 


Valeur minimale des cellules a contenu numerique. 


SUM 


Somme des cellules a contenu numerique. 



Conclusion 

Nous venons d'exposer l'utilisation de l'API pour les documents de type tableur issus 
de Calc. Apres une description de ces objets et de leur manipulation, nous avons 
aborde diverses methodes d'utilisation. Le chapitre suivant traite du maniement des 
objets Draw et des presentations Impress. 
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Les documents 
Draw et Impress 



Draw est une application de dessin, et effectivement la majeure partie de ce chapitre 
vous montrera comment creer les figures les plus diverses avec des macros. Ces 
figures ont besoin d'un support, les pages de dessin. Nous commencerons done par 
manipuler celles-ci. Comme les concepts d'arriere-plan et de couche sont bases sur le 
meme principe, nous les avons decrits a la suite, mais vous pouvez remettre a plus 
tard leur etude, et sauter ensuite a la section « Dessiner une forme ». 

Quant a Impress, e'est une application essentiellement basee sur Draw. Nous parle- 
rons dans ce chapitre essentiellement de Draw, sachant que presque tout est appli- 
cable a Impress. En fin de chapitre nous indiquerons les elements qui sont specifi- 
ques a Impress. 



API Reference sur Draw et Impress (en anglais) 

La documentation de I'API est decrite dans le Developer's Guide, chapitre Drawing Documents and 
Presentation Document. 

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ 
OpenOffice.org_Developers_Guide 
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Les pages de dessin 

Par defaut, Draw presente une seule page de dessin, mais il est possible d'en ajouter 
d'autres. Le concept est tres similaire aux feuilles du tableur Calc, mais il existe des 
differences au niveau de l'interface utilisateur et au niveau de l'API. 



Acceder aux pages existantes 

Un document Draw expose l'objet DrawPages (terme anglais pour pages de dessin) 
qui est la collection des pages du document. Le nombre actuel de pages est expose 
par la propriete Count de l'objet DrawPages. On accede a une page particuliere par 
son numero d'ordre, compte a partir de zero, avec la methode getBylndex. Avec 
OOoBasic, le getBylndex peut etre omis, comme si on indexait une variable tableau. 
Chaque page du document Draw est elle-meme un objet. Le nom interne d'une page 
nous est indique dans sa propriete Name. Le nom de la page pour l'interface utilisa- 
teur est indique par la propriete LinkDisplayName. En appliquant ces notions nous 
allons enumerer les pages d'un document Draw : 

rem CodelO-Ol.odg bibli : Pages Modulel 
Option Explicit 

Sub EnumererPagesO 

Dim monDocument As Object, lesPages As Object, unePage As Object 
Dim x As Long, nbP As Long 

monDocument = Thi sComponent 
lesPages = monDocument. DrawPages 
I nbP = lesPages. Count 

MsgBox("Nombre de pages : " & nbP) 
for x = 0 to nbP -1 
unePage = lesPages(x) 

MsgBox("Page de rang : " & x & chr(13) & _ 

"Nom interne : " & unePage. Name & chr(13) & _ 
"Nom pour 1 'utilisateur : " & unePage. LinkDisplayName) 

next 
End Sub 



Les risques des pages non renommees 

La gestion des pages de Draw est differente de celle de Calc, pour les pages ayant 
garde leur nom par defaut. Chaque page de dessin comporte un nom, visible dans le 
volet Pages. Par defaut, dans la version localisee en francais, elles sont baptisees 
Diapo 1, Diapo 2, etc. Le numero de page utilise est le rang de la vignette dans le 
volet Page, compte a partir du haut. Notez ces particularites : 
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• Dans le volet Pages, deplacez avec la souris une vignette de page non renommee : 
son nom change pour refleter sa position dans la liste, ainsi que pour les autres 
pages non renommees. Le nom interne change egalement. 

• Relisez attentivement les noms de page affiches par la macro : la propriete Name 
donne un nom different pour les pages non renommees ! En effet, la page 
Diapo 2 a pour nom interne page2. 

• Les noms affiches pour les pages non renommees dependent de la langue de 
l'interface utilisateur ! Ainsi, le meme document affichera en francais Di apo 2 ; 
en anglais Slide 2 ; en allemand Folie 2. Cependant, le nom interne, la pro- 
priete Name, indiquera toujours page2 , car c'est un nom anglais. 

Pour eviter toutes ces bizarreries, une seule solution : renommer chaque page. 



Renommer une page 

Lutilisateur peut changer l'ordre des pages, done vous ne pouvez vous fier a l'index 
pour retrouver une page particuliere. Le seul moyen sur d'obtenir l'objet page que 
Ton souhaite consiste a utiliser son nom interne (propriete Name), et encore, a condi- 
tion que la page ait ete renommee. L'objet DrawPages nous fournit pour cela la 
methode getByName, qui prend en argument le nom de la page souhaitee et renvoie 
l'objet correspondant, s'il existe. S'il n'existe pas, une erreur se produira ; aussi l'objet 
DrawPages nous donne le moyen de tester l'existence d'une page d'un nom donne 
avec la fonction hasByName qui renvoie True dans le cas positif. 

Nous allons utiliser ces notions pour renommer une page. Pour cela, il suffit de 
modifier la propriete Name de la page. Apres quoi, nous executerons la macro prece- 
dente pour lister les differentes pages. 

rem CodelO-01 . odg bibli : Pages Module2 
Option Explicit 

Sub RenommerPageO 

Dim monDocument As Object, lesPages As Object, unePage As Object 
Dim noml As String, nom2 As String 
monDocument = Thi sComponent 
lesPages = monDocument . DrawPages 

noml = InputBox("Nom actuel de la page") 
if 1 esPages . hasByName (noml) then 

nom2 = InputBox("Nouveau nom pour la page") 
1 recuperer la page "noml" 
unePage = 1 esPages . getByName (noml) 
unePage.Name = nom2 ' renommer cette page 
EnumererPages ' lister les pages du document 



Manipuler les documents OpenOffice.org 

Troisieme partie 



el se 

MsgBox(noml & " n'existe pas", 16) 
end "if 
End Sub 

Executez la macro, vous verrez le nom de la vignette concernee changer. Attention a la 
casse : les noms de pages doivent etre ecrits en respectant les majuscules et minuscules. 



Piece Pages du meme nom 

La fonction API de renommage accepte sans sourciller un nom de page existante ! Vous obtenez alors 
deux ou plusieurs pages du meme nom, et la fonction getByName vous renvoie une des pages existan- 
tes. L'interface utilisateur, au contraire, verifie le nom avant de renommer la page ; faites-en autant. 



En renommant une page avec une chaine de caracteres vide, la page redevient « non- 
renommee ». 



Ajouter une nouvelle page 

La fonction i nsertNewBylndex de l'objet DrawPages sert a creer une nouvelle page 
vierge apres une page existante (selon l'ordre des vignettes). Cette methode prend 
pour argument l'index de la page de reference, index compte a partir de zero. Comme 
la nouvelle page n'a pas encore ete renommee, elle aura pour nom Diapo n. La 
valeur n sera egal a l'index de la page de reference, plus 2. Si la valeur de l'argument 
est hors limites, par exemple negative, la page sera ajoutee a la fin. II nest pas vrai- 
ment pratique d'inserer une page a une position, car l'utilisateur peut modifier la 
structure du document. II est plus sur de se positionner par rapport a une page dont on 
connaitle nom. La position d'une page Draw est exposee par sa propriete Number, qui 
vaut 1 pour la premiere page, alors que nous avons besoin d'un index debutant a zero. 



Inserer en premiere position 

II n'est pas possible d'inserer une page Draw avant la premiere page actuelle. 



La fonction i nsertNewBylndex renvoie l'objet page nouvellement cree. Apres avoir 
insere la nouvelle page, nous la renommons ; ensuite nous enumerons les pages du 
document. 

rem CodelO-Ol.odg bibli : Pages Module3 
Option Explicit 
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Sub AjouterPageO 

Dim monDocument As Object, lesPages As Object 

Dim unePage As Object, PI As Object 

Dim noml As String, nom2 As String, idx As Long 

monDocument = Thi sComponent 

lesPages = monDocument . DrawPages 

Do 

noml = InputBox("Inserer apres la page :") 
1 reposer la question en cas d'erreur 

Loop Until lesPages. hasByName(noml) 

PI = lesPages .getByName(noml) 

idx = PI. Number -1 ' position de la page "noml" 
nom2 = InputBox("La nouvelle page aura pour nom :") 
' inserer a droite de la page "noml" 
unePage = 1 esPages . insertNewBylndex(idx) 
unePage.Name = nom2 ' renommer la page creee 
EnumererPages ' lister les pages du document 
End Sub 



Supprimer une page 

La methode remove de l'objet DrawPages supprime l'objet page fourni en argument. 
Cet exemple demande un nom de page a supprimer ; si la chaine de caracteres est 
nulle c'est que la demande est annulee ; autrement nous verifions qu'une page de ce 
nom existe avant de la supprimer. 

rem CodelO-01 . odg bibli : Pages Module4 
Option Explicit 

Sub SupprimerPageO 

Dim monDocument As Object, lesPages As Object, unePage As Object 
Dim noml As String 
monDocument = Thi sComponent 
lesPages = monDocument . DrawPages 

Do 

noml = InputBox("Page a supprimer ?") 

if noml = "" then exit sub ' annulation, ne rien supprimer 
' reposer la question en cas d'erreur 
Loop Until 1 esPages . hasByName(noml) 

unePage = lesPages. getByName(noml) ' recuperer l'objet page 
lesPages. remove(unePage) ' supprimer la page 
End Sub 
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Dupliquer une page 

L'objet document Draw permet de dupliquer une page existante, avec ses dessins, 
grace a la methode duplicate. Elle recoit en argument l'objet page a dupliquer, et 
renvoie l'objet page cree. La nouvelle page sera inseree apres la page de reference. Ici 
aussi, elle sera creee « non renommee ». 

rem CodelO-Ol.odg bibli : Pages Module5 
Option Explicit 

Sub DupliquerPageO 

Dim monDocument As Object, lesPages As Object 

Dim unePage As Object, clone As Object, noml As String 

monDocument = Thi sComponent 

lesPages = monDocument . DrawPages 

Do 

noml = InputBox("Page a dupliquer ?") 

if noml = "" then exit sub ' annulation, ne pas dupliquer 

' reposer la question en cas d'erreur 
Loop Until lesPages. hasByName(noml) 
unePage = 1 esPages . getByName(noml) 

clone = monDocument. dupl icate(unePage) 

EnumererPages ' lister les pages du document 
End Sub 



Deplacer une page dans la liste des pages 

Les fonctions de l'API ne permettent pas de modifier l'ordre des pages, alors que 
l'interface utilisateur peut le faire. 

La page visible par l'utilisateur 

La page visible dans l'interface utilisateur est appelee en anglais current page (page 
courante). Nous pouvons la recuperer avec la propriete CurrentPage de l'objet con- 
troleur associe au document. Pour rendre visible une autre page, il suffit de l'affecter a 
la propriete CurrentPage. 

rem CodelO-Ol.odg bibli : Pages Module6 
Option Explicit 

Sub PageVisibleO 

Dim monDocument As Object, lesPages As Object, unePage As Object 
Dim textel As String, nom2 As String 
monDocument = Thi sComponent 
lesPages = monDocument . DrawPages 
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unePage = monDocument.CurrentController .CurrentPage 

textel = "Page active : " & unePage.Name & chr(13) 
nom2 = InputBox(textel & "Quelle page rendre active ?") 
if 1 esPages . hasByName(nom2) then 

unePage = 1 esPages . getByName(nom2) 

monDocument.CurrentController .CurrentPage = unePage 
end if 
End Sub 



Les arriere-plans 

Draw peut utiliser des pages d'arriere-plan (en anglais Master page). Une page ordi- 
naire est toujours liee a une page d'arriere-plan. Tout ce qui se trouve sur une page 
d'arriere-plan apparaitra en fond pour les pages qui l'utilisent. L'interface utilisateur 
de Draw permet de changer l'arriere-plan d'une page en le choisissant parmi plu- 
sieurs modeles (cliquer avec le bouton droit sur la page, puis activer Page>Conception 
de diapo). Pour acceder au mode d'affichage arriere-plan, utiliser le menu Affi- 
cher>Masque. La version francaise appelle curieusement Masque ce qui est un arriere- 
plan. Dans cet affichage, le contenu d'un arriere-plan est affiche et le volet Pages 
liste maintenant les arriere-plans disponibles. II est possible de les renommer, de sup- 
primer un arriere-plan inutilise, d'en creer d'autres. 

Comme les arriere-plans sont geres de maniere un peu similaire aux pages, nous 
allons suivre la meme demarche dans la description. Attention toutefois, il y a des 
differences. 

Acceder aux arriere-plans existants 

Nous accedons facilement a l'objet arriere-plan utilise par une page grace a la pro- 
priete MasterPage de celle-ci : 

Dim arrPlan As Object 
arrPlan = maPage . MasterPage 

L'objet MasterPages (notez le s final) du document Draw est la collection des 
arriere-plans disponibles dans le document. Le nombre actuel d'arriere-plans est 
fourni par la propriete Count de l'objet MasterPages. On accede a un des arriere- 
plans par son numero d'ordre avec la methode getBylndex de la collection. Avec 
OOoBasic, le getBylndex peut etre omis, comme si on indexait une variable tableau. 
Lindex demarre a zero. Le nom d'un arriere-plan nous est indique dans sa propriete 
Name. L'enumeration des arriere-plans est calquee sur celle des pages. Le document 
du Zip telechargeable comporte plusieurs arriere-plans pour etre plus interessant. 
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rem CodelO-Ol.odg bibli : MasterP Modulel 
Option Explicit 

Sub EnumererArrierePlansO 

Dim monDocument As Object, lesArrPlans As Object, unArrPlan As Object 
Dim x As Long, nbP As Long 
monDocument = Thi sComponent 
lesArrPlans = monDocument. MasterPages 
nbP = lesArrPlans. Count 

MsgBox("Nombre de pages d ' arri ere-pl an : " & nbP) 
for x = 0 to nbP -1 

unArrPlan = lesArrPlans(x) 

MsgBox("Arri ere-pl an de rang : " & x & chr(13) & _ 
"Norn interne : " & unArrPlan.Name) 

next 
End Sub 

Le nom initial d'un arriere-plan est localise : avec une interface utilisateur en langue 
francaise, un arriere-plan insere a pour nom Standard ; si ce nom existe, OpenOffice 
choisit Standard 1, puis Standard 2, etc. Si l'interface utilisateur est en langue 
anglaise, le nom initial est Default, Default 1, etc. 

Ces noms initiaux sont gardes lorsque vous reouvrez le document avec une autre 
langue d'interface utilisateur. Si vous inserez dans un meme document des arriere- 
plans a partir de differentes localisations d'OpenOffice, vous obtiendrez un joli 
melange de noms, comme dans notre exemple. 

Renommer un arriere-plan 

Contrairement aux pages de dessin, la collection d'arriere-plans n'offre pas les 
methodes getByName et hasByName. Seul l'acces par index est possible, aussi nous uti- 
liserons une routine utilitaire, getlndexByName, que nous avons mise dans la biblio- 
theque Standard du document exemple. Elle renvoie l'index correspondant a un 
nom dans une collection. 

rem CodelO-Ol.odg bibli : MasterP Module2 
Option Explicit 

Sub RenommerArrierePlanO 

Dim monDocument As Object, lesArrPlans As Object 
Dim unArrPlan As Object 

Dim noml As String, nom2 As String, idx As Long 
monDocument = Thi sComponent 
lesArrPlans = monDocument . MasterPages 
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noml = InputBox("Nom actuel de 1 ' ami ere-pl an") 
idx = getIndexByName(lesArrPlans, noml) 

if idx >= 0 then 

nom2 = InputBox("Nouveau nom pour 1 ' arri ere-pl an") 

unArrPlan = 1 esArrPl ans (i dx) ' recuperer 1 ' arri ere-pl an "noml" 

unArrPl an . Name = nom2' renommer cet arriere-plan 

EnumererArri erePl ans 
el se 

MsgBox("Cet arriere-plan n'existe pas", 16) 
end if 
End Sub 

La routine getlndexByName renvoie un index negatif en cas d'echec. En cas de 
succes, l'index est superieur ou egal a zero. 

rem CodelO-Ol.odg bibli : Standard module Utilitaires 
Option Explicit 

' renvoie l'index de 1 'element ayant le nom donne en argument 
Function getlndexByName (collection As Object, leNom As String) As Long 
Dim x As Long 

for x = 0 to col lection. Count -1 
if coll ecti on (x) .Name = leNom then 

getlndexByName = x ' renvoyer l'index correspondant au nom 
Exit Function 
end if 
next 

getlndexByName = -1 ' valeur d'index hors limites 
End Function 



PlEGE Verifiez le nouveau nom d'arriere-plan 

La fonction API de renommage n'effectue aucun controle, contrairement a I'interface utilisateur. Ainsi, 
elle accepte sans sourciller un nom d'arriere-plan existant I Vous obtenez alors deux ou plusieurs arriere- 
plans du meme nom. Assurez-vous aussi que le nouveau nom n'est pas une chame de longueur nulle. 



Ajouter un arriere-plan 

La fonction i nsertNewBylndex de l'objet MasterPages sert a creer un nouvel arriere- 
plan vierge a la position d'un arriere-plan existant (selon l'ordre des onglets). Cette 
methode prend pour argument l'index de la page de reference. Si la valeur de l'argu- 
ment est superieure ou egale au nombre d'arriere-plans existants, la page sera ajoutee 
a la fin. La fonction i nsertNewBylndex renvoie l'objet page nouvellement cree. 

Comme tout nouvel arriere-plan, il aura le nom par defaut commencant par 
Standard (si I'interface utilisateur est en francais). Nous le renommerons done aus- 
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sitot. L'ordre d'un arriere-plan dans la collection n'ayant aucune importance, nous 
simplifierons l'exemple en le positionnant en tete. Puis, nous listerons l'ensemble de 
la collection. 

rem CodelO-Ol.odg bibli : MasterP Module3 
Option Explicit 

Sub AjouterArrierePlanO 

Dim monDocument As Object, lesArrPlans As Object, unArrPlan As Object 
Dim nom As String 
monDocument = Thi sComponent 
lesArrPlans = monDocument . MasterPages 

nom = InputBox("Nom de 1 ' arri ere-pl an a creer") 

' inserer en premiere place 

unArrPlan = lesArrPlans. insertNewBylndex(O) 

unArrPl an . Name = nom ' renommer 1 ' arri ere-pl an 

EnumererArri erePl ans 

End Sub 



Supprimer un arriere-plan 

La methode remove de l'objet MasterPages supprime l'objet arriere-plan fourni en 
argument. 

rem CodelO-Ol.odg bibli : MasterP Module4 
Option Explicit 

Sub SupprimerArrierePlanO 

Dim monDocument As Object, lesArrPlans As Object, unArrPlan As Object 
Dim noml As String, idx As Long 
monDocument = Thi sComponent 
lesArrPlans = monDocument . MasterPages 

Do 

noml = InputBox("Arri ere-pl an a supprimer ?") 

if noml = "" then exit sub ' annulation, ne rien supprimer 

' reposer la question en cas d'erreur 

idx = getIndexByName(l esArrPl ans , noml) 
Loop Until idx >= 0 
' recuperer 1 ' arri ere-pl an 
unArrPlan = lesArrPlans(idx) 

lesArrPlans. remove(unArrPl an) ' supprimer 1 ' arri ere-pl an 
End Sub 

II n'est pas possible de supprimer un arriere-plan utilise par une des pages du docu- 
ment. La methode remove ne declenche pas d'erreur, mais ne fait rien. 
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Dupliquer un arriere-plan 

II n'existe pas de fonction permettant de dupliquer un arriere-plan. 

Deplacer un arriere-plan dans la liste des arriere-plans 

II n'existe pas de fonction permettant de deplacer un arriere-plan dans la liste. Ce 
n'est pas non plus possible avec l'interface utilisateur. 

Affecter un arriere-plan a une page 

L'arriere-plan utilise par une page est expose par sa propriete MasterPage (notez le 
singulier). Pour que la page utilise un autre arriere-plan, il suffit de modifier cette 
propriete. La macro ci-dessous reprend des sequences deja vues ; la seule instruction 
nouvelle est a la fin. 

rem CodelO-01 . odg bibli : MasterP Module5 
Option Explicit 

Sub AffecterArrierePlanAPageO 

Dim monDocument As Object, unePage As Object, 1 esPages As Object 
Dim unArrPlan As Object, lesArrPlans As Object 
Dim idx As Long, nomP As String, nomArr As String 
monDocument = Thi sComponent 

lesPages = monDocument . DrawPages 
Do 

nomP = InputBox("Nom de la page ?") 

if nomP = "" then exit sub ' annulation, ne rien supprimer 

' reposer la question en cas d'erreur 
Loop Until 1 esPages . hasByName(nomP) 
unePage = 1 esPages . getByName(nomP) 

lesArrPlans = monDocument .MasterPages 
Do 

nomArr = InputBox("Arri ere-pl an a appliquer ?") 

if nomArr = "" then exit sub ' annulation, ne rien supprimer 

idx = getIndexByName(lesArrPlans, nomArr) 

' reposer la question en cas d'erreur 
Loop Until idx >= 0 
unArrPlan = lesArrPlans(idx) 

' appliquer l'arriere-plan choisi a la page choisie 
unePage. MasterPage = unArrPlan 
End Sub 
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Nous avons signale qu'il n'est pas possible de supprimer un arriere-plan utilise par 
une des pages du document. Le seul moyen de verifier qu'un arriere-plan n'est pas 
utilise est de balayer toutes les pages et de verifier 1' arriere-plan que chacune utilise. 



Les couches 

Ici aussi nous allons trouver des mecanismes similaires de gestion de « page », mais encore 
differents. Notez que la notion de couches existe seulement pour Draw, pas Impress. 

Acceder aux couches existantes 

L'objet Layer-Manager (anglais pour gestionnaire de couches) est la collection des 
couches d'un document Draw. Le nombre actuel de couches est fourni par la pro- 
priete Count de l'objet LayerManager. On accede a une des couches par son numero 
d'ordre avec la methode getBylndex de la collection. Avec OOoBasic, le getBylndex 
peut etre omis, comme si on indexait une variable tableau. L'index demarre a zero. Le 
nom d'une couche nous est indique dans sa propriete Name. Lenumeration des cou- 
ches est calquee sur celle des pages. Le document du Zip telechargeable comporte 
plusieurs couches pour etre plus interessant. 

rem CodelO-01 . odg bibli : Couches Modulel 
Option Explicit 

Sub EnumererCouchesO 

Dim monDocument As Object, lesCouches As Object, uneCouche As Object 
Dim x As Long, nbP As Long 
monDocument = Thi sComponent 

lesCouches = monDocument . LayerManager 
nbP = lesCouches. Count 

MsgBox("Nombre de couches : " & nbP) 
for x = 0 to nbP -1 

uneCouche = lesCouches(x) 

MsgBox("Couche de rang : " & x & chr(13) & _ 
"Nom interne : " & uneCouche. Name) 

next 
End Sub 

En executant la macro vous constatez que les couches predefinies affichent des noms 
internes, qui sont en anglais : 

• 1 ayout = mise en page 

• controls = controles 
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• measure"! ines = lignes de cote 

• background = arriere-Plan 

• backgroundobjects = objets d'arriere-plan 

Les couches et I'interface utilisateur 

L'interface utilisateur n'affiche pas toutes les couches existantes. La couche Objets 
d'arriere-plan n'est visible qu'en affichage Masque. La couche Arriere-plan n'est 
jamais visible. II en resulte que l'ordre des onglets des couches ne reflete pas l'ordre 
dans la collection LayerManager. 

Les noms des couches predefinies apparaissent sur les onglets dans la langue de 
l'interface utilisateur, mais le nom interne est en anglais. Cependant, la fonction 
hasByName reconnait aussi le nom localise. 



Information 

Avec l'interface anglaise, les onglets des couches par defaut ont aussi un nom different du nom interne. 



Renommer une couche 

Comme pour les pages de dessin, le gestionnaire de couches expose les methodes 
getByName et hasByName. 

rem CodelO-01 . odg bibli : Couches Module2 
Option Explicit 

Sub RenommerCoucheO 

Dim monDocument As Object, lesCouches As Object, uneCouche As Object 
Dim noml As String, nom2 As String, idx As Long 
monDocument = Thi sComponent 
lesCouches = monDocument . LayerManager 

noml = InputBox("Nom actuel de la couche") 
if lesCouches. hasByName (noml) then 

nom2 = InputBox("Nouveau nom pour la couche") 

uneCouche = lesCouches. getByName(noml) 

uneCouche. Name = nom2 1 renommer cette couche 

EnumererCouches ' lister les couches du document 
el se 

MsgBox("Cette couche n'existe pas", 16) 
end if 
End Sub 
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Piece Verifiez le nouveau nom de couche 

La fonction API de renommage n'effectue aucun controle, contrairement a I'interface utilisateur. Ainsi, 
elle accepte sans sourciller un nom de couche existant ! Vous obtenez alors deux ou plusieurs couches du 
meme nom. [.'interface utilisateur, au contraire, verifie le nom avant de renommer la page ; faites-en 
autant. Assurez-vous aussi que le nouveau nom n'est pas une chatne de longueur nulle, ni identique a 
celui d'une des couches par defaut. 



Ajouter une couche 

La fonction i nsertNewBylndex de l'objet LayerManager sert a creer une nouvelle 
couche vierge a la position d'une couche existante (selon l'ordre interne des couches, 
pas l'ordre des onglets visibles). Cette methode prend pour argument l'index de la 
couche de reference. Comme la nouvelle couche n'a pas encore ete renommee, elle 
aura pour nom CoucheN avec pour N un numero egal au nombre total d'onglets visi- 
bles en mode d'affichage Normal. Si la valeur de l'argument est superieure ou egale 
au nombre de couches existantes, la nouvelle sera ajoutee a la fin. La fonction 
i nsertNewBylndex renvoie l'objet page nouvellement cree. 

Rem CodelO-Ol.odg bibli : Couches Module3 
Option Explicit 

Sub AjouterCouche() 

Dim monDocument As Object, lesCouches As Object, uneCouche As Object 
Dim noml As String, nom2 As String, idx As Long 
monDocument = Thi sComponent 
lesCouches = monDocument . LayerManager 

Do 

noml = InputBox("Inserer a 1 ' empl acement de la couche :") 

' reposer la question en cas d'erreur 
Loop Until lesCouches.hasByName(noml) 
' position de la couche "noml" 
idx = getIndexByName(lesCouches, noml) 
nom2 = InputBox("La nouvelle couche aura pour nom :") 
' inserer a la position de la couche "noml" 
uneCouche = 1 esCouches . i nsertNewByIndex(i dx) 
uneCouche . Name = nom2 ' renommer la couche creee 
EnumererCouches ' lister les couches du document 
End Sub 

Pour obtenir l'index d'une couche connaissant son nom, nous emploierons la routine 
utilitaire getlndexByName que nous avons decrite plus haut, a propos des arriere-plans. 
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Nom initial des couches 

Le nom initial choisi par OpenOffice depend de la langue de I'interface utilisateur. Dans la version fran- 
gaise d'OpenOffice, une couche inseree a pour nom CoucheN . Dans la version anglaise d'OpenOffice, 
le nom initial est LayerN. Ces noms initiaux sont conserves lorsque vous ouvrez le document dans une 
autre version localisee. Si vous inserez dans un meme document des couches a partir de differentes loca- 
lisations d'OpenOffice, vous obtiendrez un joli melange de noms. 



Supprimer une couche 

La methode remove, de l'objet Layer-Manager, supprime l'objet couche fourni en 
argument. Un bogue (Issue 90705) rend cette fonction inefficace si elle est executee 
depuis l'EDI. Executez la macro depuis le document Draw. 

rem CodelO-Ol.odg bibli : Couches Module4 
Option Explicit 

Sub SupprimerCoucheO 

Dim monDocument As Object, lesCouches As Object, uneCouche As Object 
Dim noml As String 
monDocument = Thi sComponent 
lesCouches = monDocument . LayerManager 

Do 

noml = InputBox("Couche a supprimer ?") 

if noml = "" then exit sub ' annulation, ne rien supprimer 

' reposer la question en cas d'erreur 
Loop Until 1 esCouches . hasByName(noml) 
uneCouche = lesCouches .getByName(noml) 
1 esCouches . remove (uneCouche) 
End Sub 

II est possible de supprimer une couche utilisee par des formes (dessins) du docu- 
ment. Celles-ci disparaissent avec la couche. 



PlEGE Couches par defaut 

II est possible par programmation de supprimer les pages par defaut. OpenOffice.org manifeste ensuite sa 
disapprobation avec une erreur logicielle et un plantage a la fermeture du fichier ! Done, ne faites pas ca. 



Dupliquer une couche 

II n'existe pas de fonction permettant de dupliquer une couche. 
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Deplacer une couche dans la liste des arriere-plans 

II n'existe pas de fonction permettant de deplacer une couche dans la liste. Ce n'est 
pas non plus possible avec l'interface utilisateur. 



Les proprietes d'une couche 

En dehors de la propriete Name, de type String, que nous avons deja utilisee, une 
couche dispose de trois autres proprietes interessantes, toutes de type Bool ean qu'on 
peut lire et modifier : 

• IsLocked : si True, la couche est verrouillee, 

• IsPri ntabl e : si True, les objets de la couche sont imprimables, 

• IsVi si bl e : si True, les objets de la couche sont visibles. 

La macro doit etre executee depuis la fenetre Draw, et non depuis l'EDI. Modifiez 
ces proprietes de la maniere suivante : 

uneCouche.IsVisible = False ' rendre la couche invisible 
ThisComponent.CurrentController.IsMasterPageMode = False 

La deuxieme instruction a pour but de rendre effectif en affichage la modification de 
la propriete, pour les couches predefinies. C'est un contournement du bogue 
Issue 97955. Avec l'interface utilisateur, l'onglet d'une couche invisible change de 
couleur ; ce n'est pas le cas pour un changement par programme. 



Changement du mode d'affichage 

Le mode d'affichage Normal, ou Masque (arriere-plan) depend de l'indicateur boo- 
leen IsMasterPageMode de l'objet CurrentCont roller . Le mettre a True permet de 
passer au mode Masque. 

ThisComponent.CurrentController. IsMasterPageMode = True 



Bogues 

En principe, il devrait etre possible de changer I'arriere-plan visible en modifiant la propriete 
Cur rent Page de l'objet CurrentCont roller. En realite, I'effet est imprevisible en raison de dif- 
ferents bogues. 
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Les proprietes (Tune page de dessin 

Le tableau 10-1 liste les principales proprietes d'une page de dessin. Les arriere- 
plans ont les memes proprietes, excepte bien sur MasterPage qui n'existe pas. 

Tableau 10-1 Proprietes d'une page de dessin 



Name 


Stri ng 


Norn interne de la page. 


Li nkDi spl ayName 


Stri ng 


Nom de la page, pour I'utilisateur. 


BorderLeft 


Long 


Marge de gauche en 1 /1 00 de mm. 


BorderRi ght 


Long 


Marge de droite en 1/100 de mm. 


BorderTop 


Long 


Marge du haut en 1/100 de mm. 


BorderBottom 


Long 


Marge du bas en 1/100 de mm. 


Height 


Long 


Hauteur totale de la page en 1 /1 00 de mm. 


Width 


Long 


Largeur totale de la page en 1 /1 00 de mm. 


Number 


Integer 


Rang de la page dans I'ordre des vignettes du volet Pages de la 
fenetre Draw. Numerotation a partir de 1 ; en lecture seulement. 


Orientation 


Long 


Orientation de la page a I'impression, constante nommee. 


MasterPage 


Object 


Arriere-plan utilise par la page. 


Count 


Long 


Nombre de formes sur la page. 


Forms 


Object 


Collection des formes sur la page. 



La propriete Ori entati on ne concerne que I'impression, elle ne change pas la visuali- 
sation de la page. Elle ne peut prendre que deux valeurs : 

com . sun . star . vi ew. PaperOri entati on . PORTRAIT 
com . sun . star . vi ew. PaperOri entati on . LANDSCAPE 

Attention a la casse ! Les constantes nominees doivent etre ecrites en respectant les 
majuscules et minuscules. 



Dessiner une forme 

Nous appellerons forme (en anglais shape) un dessin elementaire, par exemple un rec- 
tangle ou une ellipse. Ne confondez pas avec l'anglais form, qui designe un formulaire 
dans le jargon OpenOffice.org. 

Les formes sont dessinees sur une page de dessin, c'est-a dire une page ordinaire de 
Draw ou une diapo d'Impress, ou un arriere-plan. 
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Dessiner une forme consiste a ajouter une nouvelle forme sur une page de dessin ou 
sur un arriere-plan. Void un exemple, les commentaires suivent. 

I rem CodelO-02 .odg bibli : Ajouter Modulel 
Option Explicit 

Sub AjouterEll i pse() 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim dimensionsForme As New com. sun. star. awt. Size 
Dim positionForme As New com. sun. star .awt. Point 

monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi nl") 

maForme = monDocument. createlnstanceC 

"com . sun . star . drawi ng . El 1 i pseShape") 

dimensionsForme. Width = 13400 ' 134 mm de large 
dimensionsForme. Height = 2530 ' 25,3 mm de haut 
positionForme. x = 2500 ' 25 mm a droite du coin de la page 
positionForme. y = 5300 ' 53 mm en dessous du coin de la page 

maForme. Size = dimensionsForme 
maForme. Posit ion = positionForme 
maPage . add (maForme) 

End Sub 

Dans un premier temps, nous obtenons une forme virtuelle grace a la fonction 
createlnstance de l'objet document. Nous avons choisi une ellipse, mais d'autres 
variantes de formes existent. Avant de l'ajouter sur la page, il faut la dimensionner et 
preciser ou elle sera positionnee. Ceci est realise avec deux structures que nous 
retrouverons souvent. 

Les dimensions d'une forme (size en anglais) sont celles du rectangle qui l'englobe. 
Pour les indiquer, nous avons besoin d'une structure com . sun . star . awt . Si ze (voir 
le tableau 10-2). 



Tableau 10-2 Structure Size 





Type 




Width 


Long 


Largeur, en 1/100 de mm. 


Height 


Long 


Hauteur, en 1/100 de mm. 



La position d'une forme est definie par les distances horizontale et verticale entre le 
coin en haut a gauche de la page de dessin et le coin du haut a gauche du rectangle 
qui englobe la forme. Pour indiquer une position, nous utilisons une structure 
com . sun . star . awt . Poi nt (voir le tableau 10-3). 
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Tableau 10-3 Structure Point 





X 


Long 


Position horizontal^ en 1/100 de mm. 


Y 


Long 


Position verticale, en 1/100 de mm. 



A RETENIR Position dans I'interface utilisateur 

Les coordonnees de position affichees par I'interface utilisateur se referent au coin en haut a gauche de la 
zone imprimable de la page. II y a done une difference, correspondant aux marges horizontale et verticale. 

Une fois ces deux structures remplies, nous les copions sur les proprietes Size et 
Position de l'objet forme. Avant de definir d'autres proprietes, que nous decrirons 
plus loin, il faut ajouter notre forme virtuelle sur la page grace a sa methode add. La 
forme apparait. II est encore possible de modifier les proprietes de position et dimen- 
sion de la forme apres l'avoir ajoutee. 

Pour ajouter une forme a un arriere-plan, la seule difference par rapport au para- 
graphe precedent est qu'il faut utiliser la methode add de l'arriere-plan au lieu de 
celle de la page de dessin. 

Les differents types de forme (rectangle, ellipse, etc.) sont decrits plus loin. Aupara- 
vant, nous allons voir comment retrouver une forme existante. 



Trouver une forme existante 

Trouver une forme nommee 

Lutilisateur peut nommer une forme (cliquer avec le bouton droit sur la forme selec- 
tionnee). En fait, il peut nommer ainsi tout objet sur la page. Le nom de la forme est 
expose dans sa propriete Name, de type String. Par programmation, nommer une 
forme se fait tees simplement : 

maForme . Name = "Ma premiere forme" 



PlEGE Noms des objets sur une page 

Avec I'interface utilisateur il est impossible de donner le meme nom a deux objets (dessin, image, etc.) 
sur une meme page. Par contre I'API n'effectue aucun controle quand vous modifiez la propriete Name ! 
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Une page de dessin est un conteneur de formes. Malheureusement, ce conteneur ne 
sait pas retrouver une forme par son nom, mais seulement par un index avec la 
methode getBylndex de la page Draw. Avec OOoBasic, le getBylndex peut etre 
omis, comme si on indexait une variable tableau. Void un exemple : 

maForme = maPage(3) 

Ceci ne nous avance pas beaucoup, car nous ne connaissons pas l'ordre des dessins 
dans l'objet page. Pire, les objets recuperes par getBylndex ne sont pas uniquement 
des formes, mais aussi des images ou d'autres objets graphiques. Nous allons utiliser 
une fonction utilitaire de l'annexe B, la fonction Fi ndObjectByName, qui prend 
comme argument l'objet page de dessin et le nom du dessin recherche. Elle explore la 
collection des formes et images et retourne l'objet qui a le nom demande. En cas 
d'echec, la fonction renvoie un objet Nul 1 . 

Un exemple typique, que nous retrouverons souvent dans la section consacree aux 
proprietes des formes, est reproduit ci-dessous. Nous obtenons directement la page 
nommee Dessin3, puis nous utilisons Fi ndObjectByName pour obtenir l'objet forme 
nomme F4 qui se trouve dans cette page. 

Dim monDocument As Object, maPage As Object, maForme As Object 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi n3") 
maForme = Fi ndObjectByName (maPage, "F4") 

La routine Fi ndObjectByName est recopiee dans la bibliotheque Standard des docu- 
ments exemples qui l'utilisent. 

Trouver les formes selectionnees par l'utilisateur 

S'il y a selection, les elements selectionnes sont obligatoirement sur la page de dessin 
visible. Or, nous savons deja retrouver la page visible. L'objet CurrentSelection, 
expose par le document Draw ou Impress, nous fournit la collection des formes 
selectionnees par l'utilisateur. Mais attention, s'il n'a rien selectionne, cet objet est 
Null. Chaque objet selectionne est accessible par la methode getBylndex de la col- 
lection, ou en Basic par une simple indexation. 

Ces remarques sont mises en oeuvre dans le code suivant, qui affiche le texte de cha- 
cune des formes selectionnees. 

rem CodelO-04 . odg bibli : Selections Modulel 
Option Explicit 
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Sub SelectionslltilisateurO 

Dim monDocument As Object, maPage As Object 

Dim lesFormes As Object, maForme As Object, n As Long 

monDocument = Thi sComponent 

maPage = monDocument. CurrentController .CurrentPage 
lesFormes = monDocument .CurrentSel ection 
if IsNul 1 (1 esFormes) then 

print "Aucune selection !" 
el se 

for n = 0 to lesFormes. Count -1 
maForme = 1 esFormes (n) 

print n, maForme. Text. String 
next 
end if 
End Sub 

Vous remarquerez en faisant des essais que l'ordre des formes dans la collection n est 
pas toujours identique a l'ordre des selections. 

Selectionner visiblement une forme 

Supposons que nous ayons besoin de selectionner une forme nommee unTri angle 
qui se trouve dans la page nommee Dessi ns du document. En selectionnant la forme 
avec la methode select de l'objet CurrentController, la page est automatiquement 
rendue visible. 

rem CodelO-04 . odg bibli : Selections Module2 
Option Explicit 

Sub SelectionnerFormeO 

Dim monDocument As Object, maPage As Object, maForme As Object 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi ns") 
maForme = FindObjectByName(maPage, "unTri angl e") 
if IsNull (maForme) then 

print "II n'existe aucune forme de ce nom" 
el se 

monDocument . Cur rentControl 1 er . sel ect (maForme) 

end if 
End Sub 



Lister les formes d'une page 

L'ensemble des formes (et images) d'une page est disponible dans une collection 
geree par la page. La propriete Count de l'objet page nous renseigne sur le nombre 
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d'objets sur la page et, grace a Basic, nous avons acces a chacun d'eux par simple 
indexation de l'objet page. 

Dans cet exemple, nous allons enumerer les formes ordinaires d'une page. Nous evi- 
terons de lister les autres objets eventuels (image, diagramme, dessin 3D), en testant 
si le service LineProperties est supporte. Nous afficherons le type de chaque forme 
en utilisant la propriete ShapeType. 

rem CodelO-04 . odg bibli : Selections Module6 
Option Explicit 

Sub EnumererFormes2D() 

Dim monDocument As Object, maPage As Object 

Dim lesFormes As Object, maForme As Object 

Dim nomP As String, n As Long 

' rechercher seulement les formes 2D 

Const serv = "com. sun. star. drawing. LineProperties" 

monDocument = Thi sComponent 

nomP = InputBox("Donnez un nom de page") 

if not monDocument . DrawPages . hasByName(nomP) then exit sub 
maPage = monDocument . DrawPages . getByName(nomP) 
for n = 0 to maPage. Count -1 
maForme = maPage(n) 

if maForme. supportsService(serv) then 

monDocument . CurrentControl 1 er . sel ect (maForme) 
MsgBox("Forme " & n & chr(13) & "Type = " & _ 

maForme. ShapeType & chr(13) & " Nom = " & maForme . Name) 
end if 
next 

monDocument. CurrentController.select(Null) ' plus de selection 
End Sub 



Supprimer une forme 

La methode remove de l'objet page de dessin supprime la forme fournie en argument. 

rem CodelO-02 . odg bibli : Ajouter Module2 
Option Explicit 

Sub SupprimerFormeO 

Dim monDocument As Object, maPage As Object 
Dim lesFormes As Object, maForme As Object 
monDocument = Thi sComponent 
lesFormes = monDocument . DrawPages 
maPage = 1 esFormes . getByName("Dessi n2") 
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maForme = FindObjectByName(maPage, "cubel") 
maPage. remove (maForme) 
End Sub 

Le principe est identique pour supprimer une forme d'une couche ou d'un arriere-plan. 



Pour manipuler les proprietes d'une forme, nous utiliserons des formes nominees 
dans une page de dessin du document CodelO-02 . odg. Si vous creez une forme, com- 
mencez par l'inserer dans la page avant de modifier ses proprietes. 



Type de la forme 

La propriete ShapeType, de type Stri ng, indique le type de la forme. Exemple : 



"com. sun. star. drawing. Ell ipseShape" 

La liste des differents types de formes possibles est indiquee au tableau 10-25 de la 
section « Les differentes formes ». 



La position d'une forme est definie par sa propriete Position, tandis que la taille de 
la forme est definie par sa propriete Si ze. Nous avons detaille ces proprietes a la sec- 
tion « Dessiner une forme ». Vous pouvez naturellement modifier ces valeurs pour 
toute forme existante. 

Une forme possede deux proprietes de type Bool ean qui interdisent a i'utilisateur de 
modifier la taille ou la position si vous leur affectez la valeur True : 

• Si ze Protect interdit de modifier la taille, 

• Move Protect interdit de deplacer la forme. 

Mais par programmation vous pouvez toujours modifier taille et position. 



Proprietes des formes 



Position et taille de la forme 



Les liens entre forme et couche 



Toute forme est associee a une couche, et une seule. Si vous n'avez pas defini de 
couche particuliere, une forme d'une page de dessin est associee a la couche layout 
(c'est l'onglet Mise en page, en mode d'affichage normal). 
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La forme expose deux proprieties : 

• LayerName, de type Stri ng, est le nom interne de la couche associee, 

• LayerlD, de type Integer, est le rang interne de la couche associee. 

De son cote, le gestionnaire de couches (aussi appele LayerManager), indique dans 
quelle couche se trouve une forme avec la fonction getLayerForShape. Cette der- 
niere recoit en argument un objet forme et renvoie un objet couche. 

L'exemple qui suit liste, pour chaque forme de la page de dessin, le nom de la forme 
et le nom de la couche associee, obtenu des deux manieres. 

rem CodelO-02 . odg bibli : CoucheForme Modulel 
Option Explicit 

Sub Affi cherCoucheDesObjetsO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim lesCouches As Object, maCouche As Object, x As Long 
monDocument = Thi sComponent 
lesCouches = monDocument . LayerManager 
maPage = monDocument . DrawPages . getByName("Dessi n4") 
for x = 0 to maPage. Count -1 ' toutes les formes de la page 
maForme = maPage(x) 

maCouche = lesCouches. getLayerForShape(maForme) 

1 deux manieres de trouver le nom de la couche 
print maForme. Name, maCouche. Name, maForme. LayerName 

next 
End Sub 

Pour associer une forme a une autre couche l'API nous offre encore deux moyens : 

• changer le nom de la couche dans la propriete LayerName de la forme, 

• utiliser la methode attachShapeToLayer du gestionnaire de couches. 

Nous allons utiliser la premiere maniere pour modifier l'affectation des formes selec- 
tionnees par l'utilisateur. Exceptee la ligne concernant l'association, la macro utilise 
des principes decrits dans les sections precedentes. 

rem CodelO-02 . odg bibli : CoucheForme Module2 
Option Explicit 

Sub Associ erFormeAcouche() 

Dim monDocument As Object, f As Long, nc As String 

Dim lesFormes As Object, maForme As Object 

Dim lesCouches As Object, maCouche As Object 

monDocument = Thi sComponent 

lesCouches = monDocument . LayerManager 

Do 

nc = InputBox("Nom de la couche a associer" & chr(13) & _ 
" aux formes sel ecti onnees") 
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Loop Until 1 esCouches . hasByName(nc) 
lesFormes = monDocument . CurrentSel ecti on 
if IsNull (lesFormes) then exit sub 

for f = 0 to 1 esFormes . Count -1 ' les formes sel ecti onnees 
maForme = lesFormes(f) 

maForme. LayerName = nc' associer a la couche choisie 
next 
End Sub 

La deuxieme maniere se ferait ainsi : 
1 esCouches. attachShapeToLayer (maForme, 1 esCouches . getByName(nc)) 



Le contour de la forme 

Le contour d'une forme utilise les proprietes de ligne, dont le tableau 10-4 liste les 
principales. Certaines de ces proprietes sont expliquees plus en detail dans le texte. Si 
vous souhaitez etudier precisement les possibilites de ligne, consultez dans l'API la 
page sur le service : com . sun . star . drawi ng . Li neProperti es . 

Tableau 10-4 Proprietes de ligne 



Propriete 


Type 


Signification 


Li neStyl e 


Long 


Genre de la ligne ; constante nommee (voir le tableau 10-5). 


Li neCol or 


Long 


Couleur de la ligne. 


Li neWi dth 


Long 


Largeurde la ligne, en 1/100 de mm. 


LineTransparence 


Integer 


Pourcentage de transparence, entre 0 (opaque) et 100 (transparent). 


Li neloi nt 


Long 


Dessin des angles de la forme ; constante nommee (voir le 
tableau 10-6). 


Li neDashName 


Stri ng 


Norn d'un tirete predefini. 


Li neDash 


Object 


Structure decrivant le tirete (voir le tableau 1 0-7). 



Le genre de la ligne, LineStyle, peut prendre les valeurs du tableau 10-5. Ce sont 
des constantes nominees de la forme : 

I com. sun .star .drawi ng . Li neStyl e . SOLID 



Tableau 10-5 Constantes de LineStyle 



Constante Signification 


NONE 


Pas de ligne, done pas de contour apparent. 


SOLID 


Ligne continue (valeur par defaut). 


DASH 


Ligne tiretee. 
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La propriete LineDoint correspond a Style d'angle dans le panneau de proprietes de 
ligne de l'interface utilisateur, et indique comment abouter deux lignes epaisses de la 
meme forme (ligne brisee, contour d'un rectangle ou d'un polygone). Elle contient 
une constante nommee dont les valeurs possibles sont listees dans le tableau 10-6. 
Exemple de valeur : 

com. sun . star .drawn ng . Li neJoi nt . MITER 

Tableau 10-6 Constantes de LineJoint 



NONE 


Les deux traits sont juxtaposes sans adaptation. 


MIDDLE 


Comme BEVEL (constante non utilisee). 


BEVEL 


Un angle biseaute est dessine a I'intersection. 


MITER 


Un angle vif est dessine a I'intersection. 


ROUND 


Un angle arrondi est dessine a I'intersection. 



Les lignes tiretees 

Les difficultes apparaissent avec les lignes tiretees, qui utilisent de nombreux para- 
metres. Le plus simple pour indiquer quel tirete est a utiliser serait de remplir la pro- 
priete Li neDashName avec le nom d'un tirete existant. Malheureusement, ces noms 
predefinis ou personnalises ne sont pas correctement integres dans le document. 
Apres divers essais et deboires, nous deconseillons son utilisation. 

La propriete LineDash decrit precisement le tiret. C'est une structure decrite au 
tableau 10-7. 



Tableau 10-7 Elements de definition d'un tirete de ligne 





Style 


Long 


Forme du tiret ; constante nommee (voir le tableau 1 0-8). 


Dots 


Integer 


Nombre de points dans le tirete. 


DotLen 


Long 


Longueur d'un point, en 1/100 de mm. 


Dashes 


Integer 


Nombre de tirets dans le tirete. 


DashLen 


Long 


Longueur d'un tiret, en 1/100 de mm. 


Di stance 


Long 


Distance entre les points ou les tirets, en 1/100 de mm. 



La forme du tiret (element Styl e de la propriete Li nedash) est une constante nommee 
dont les valeurs possibles sont listees dans le tableau 10-8. Exemple de valeur : 

I com . sun . star . drawi ng . DashStyl e . RECT 
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Tableau 10-8 Constantes de DashStyle 



RECT 


En forme de trait (rectangle). 


ROUND 


En forme de point (disque). 


RECTRELATIVE 


En forme de rectangle proportionnel a la longueur de la ligne. 


ROUNDRELATIVE 


En forme de disque proportionnel a la longueur de la ligne. 



Pour imposer par programmation la forme du tirete, il est necessaire de remplir un 
objet ayant la structure Li neDash, puis l'appliquer a la propriete Li neStyl e de la forme. 



rem Codel0-02 . odg 
Option Explicit 



bibli : Contour Modulel 



Sub Defi ni rTi reteO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim mesTirets As New com . sun . star . drawing . Li neDash 

monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi n3") 
maForme = FindObjectByName(maPage, "F4") 

With mesTirets 

.Style = com. sun. star. drawing. DashStyle. RECT 



.Dots = 4 
.DotLen = 50 
.Dashes = 2 
.DashLen = 200 
.Distance = 150 
End With 

maForme . Li neWi dth = 100 ' 1 mm d'epaisseur 
maForme . Li neDash = mesTirets 

maForme . Li neStyl e = com . sun . star . drawi ng . Li neStyl e . DASH 
End Sub 



4 points 
de 0,5 mm 
suivis de 2 ti rets 
de 2 mm 

espaces de 1,5 mm 



Le fond et la forme 



Sans instruction particuliere, la forme est creee avec une couleur de fond uniforme, 
dont le coloris est une valeur par defaut. Mais d'autres styles de remplissage du fond 
sont possibles, selon la valeur de la propriete Fi 1 1 Styl e. 
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Les styles de remplissage du fond 

Le terme « style » employe ici a seulement le sens de variante. La propriete 
Fill Style d'une forme est de type Long, et contient une constante nommee 
(tableau 10-9), de la forme : 

| com . sun . star .drawn ng . Fi 11 Sty! e . SOLID 

Tableau 10-9 Constantes de style de remplissage 



NONE 


Fond invisible (quelle que soit la valeur de Fi 1 lTransparence). 


SOLID 


Couleur uniforme (valeur par defaut). 


GRADIENT 


Degrade de couleur. 


HATCH 


Hachure. 


BITMAP 


Utilisation d'un motif bitmap (une image repetee). 



Nous allons expliquer comment utiliser chacun de ces styles de remplissage. Si vous 
souhaitez etudier dans le detail les possibilites de degrade, quadrillage, etc., consultez 
l'API a la page sur le service : com. sun. star. drawi ng . Fil 1 Properties 



Couleur de fond 

Pour imposer une couleur on donne a la propriete Fi 1 1 Col or de la forme une valeur 
de couleur. 

rem CodelO-02 . odg bibli : Proprietes Modulel 
Option Explicit 

Sub CouleurDuFondFormeO 

Dim monDocument As Object, maPage As Object, maForme As Object 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi n2") 
maForme = Fi ndObjectByName(maPage , "F2") 

maForme. Fill Col or = RGB(100 ,255,255) 

End Sub 

La couleur obtenue est repartie uniformement sur la surface de la forme. Open- 
Office. org offre une alternative, le degrade de couleur. 
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Fond en degrade de couleur 

Creer par l'API un degrade de couleurs est assez complexe, et le resultat ne peut etre 
juge que visuellement. II est preferable d'utiliser un modele de document dans lequel 
on aura defini des degrades personnels avec l'interface utilisateur. 

Pour visualiser les degrades predefinis ou ajouter des degrades dans un document, 
selectionnez une forme, cliquez avec le bouton droit, puis choisissez Remplissage, 
onglet Degrades. Vous aurez ainsi une idee de la quantite de parametres utilisables et 
de leurs effets. Chaque degrade defini comporte un nom. Malheureusement, ces 
noms predefinis ou personnalises ne sont pas correctement integres dans le docu- 
ment et nous deconseillons d'utiliser la propriete FillGradientName. 

Le degrade de remplissage d'une forme est obtenu par sa propriete Fill Gradient. 
C'est une structure dont les elements sont indiques dans le tableau 10-10. Vous y 
retrouvezles parametres de l'interface utilisateur, panneau Remplissage, onglet Degrades. 

Tableau 10-10 Proprietes d'un degrade 



Propriete 






Style 


Long 


Genre du degrade (lineaire, axial, radial, etc.) ; cons- 
tante nommee (voir le tableau 10-11). 


StartColor 


Long 


Couleur initiale. 


EndColor 


Long 


Couleur finale. 


Angl e 


Integer 


Angle, en 1/10 de degre, n'utiliser que les valeurs 
positives ; le sens de rotation est I'inverse des aiguilles 
d'une montre. 


Border 


Integer 


Pourcentage de la largeur totale oil la couleur initiale 
est utilisee ; valeur de 0 a 1 00. 


XOffset 


Integer 


Pourcentage de la largeur totale ou le degrade 
commence ; valeur de 0 a 1 00. 


YOffset 


Integer 


Pourcentage de la hauteur totale oil le degrade 
commence ; valeur de 0 a 1 00. 


Startlntensi ty 


Integer 


Intensite au debut du degrade. 


Endlntensi ty 


Integer 


Intensite a la fin du degrade. 


StepCount 


Integer 


Utilise seulement dans un style de degrade. Nombre de 
pas de changement de couleur ; zero si ce nombre n'est 
pas limite. 



La propriete Style du degrade peut prendre les valeurs du tableau 10-11. Ces cons- 
tantes nominees sont de la forme : 



com . sun . star . awt . Gradi entStyl e . ELLIPTICAL 
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Tableau 10-11 Constantes de style de degrade 



Constan 



LINEAR 


Lineaire 


AXIAL 


Axial. 


RADIAL 


Radial. 


ELLIPTICAL 


Ellipso'ide. 


SQUARE 


Carre. 


RECT 


Rectangulaire. 



Le nombre de pas de changement de couleurs (ou de nuances) est precise dans la 
propriete FillGradientStepCount de la forme. Une valeur nulle donne le maximum 
de nuances de degrade. Maintenant nous en savons assez pour affecter un degrade a 
une forme : recuperer la forme, recuperer son degrade, le modifier et le restocker, et 
ne pas oublier de changer la propriete Fi 1 1 Styl e de la forme pour indiquer que le 
remplissage est un degrade. Changez les valeurs des parametres et executez la macro 
de nouveau pour observer leur impact sur le rendu. 



rem CodelO-02 . odg 
Option Explicit 



bibli : Degrades Modulel 



Sub AppliquerDegradeO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim monDegrade As Object 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi n2") 
maForme = Fi ndObjectByName(maPage , "Rect5") 

monDegrade = maForme . Fil lGradient 
With monDegrade 

.Style = com. sun. star. awt.GradientStyle. ELLIPTICAL 

.XOffset = 25 
.YOffset = 50 

.Angle = 150 1 15 degres, sens anti-horaire 
.Border = 5 

.StartColor = RCB(0, 255,0) ' vert pur 
.Startlntensity = 100 

.EndColor = RCB(0,7,255) ' bleu presque pur 
.Endlntensity = 80 
End With 

maForme . FillGradient = monDegrade 

maForme . Fill GradientStepCount = 10 ' 10 plages de couleurs 
maForme. Fill Style = com. sun. star. drawing. Fill Style. GRADIENT 

End Sub 
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Un peu de transparence 

La couleur, uniforme ou en degrade, est opaque par defaut. On peut regler sa trans- 
parence par la propriete Fi~l "ITransparence, de type Integer. Elle prend une valeur 
entre 0 et 100 qui est le pourcentage de transparence : 0 pour une couleur opaque, 100 
pour une couleur totalement transparente. 

maForme. Fill Transparence = 65 

Cette transparence est uniforme sur toute la surface de la forme, mais il est possible 
d'obtenir un degrade de la transparence ! 

Le degrade de transparence 

Contrairement aux degrades de remplissage, il nest pas possible d'appliquer un 
degrade de transparence sans le nommer. Ces noms ne sont pas accessibles par 
l'interface utilisateur, cependant tous les degrades de transparence utilises sont 
nommes, meme ceux crees par l'interface utilisateur. Seuls restent memorises dans le 
document les degrades utilises dans au moins une forme. L'application d'un degrade 
de couleur par programmation comportera plusieurs etapes : 

1 Creer et remplir une structure Gradi ent, en lui donnant un nom non utilise. 

2 Trouver un nom de degrade n'existant pas dans le conteneur de degrades transparents. 
Ce conteneur est obtenu en invoquant le service TransparencyGradi entTabl e a par- 
tir du document. 

3 Inserer sous ce nom le degrade dans le conteneur. 

4 Donner ce nom de degrade a la propriete Fi"l"ITransparenceGradientName de la 
forme. 

Bien entendu, le meme nom de degrade peut etre utilise pour plusieurs formes. 
La structure Gradi ent est utilisee de maniere particuliere : 

• Les elements StartColor et EndColor doivent contenir une valeur de gris corres- 
pondant aux valeurs initiale et finale de transparence. Le noir complet correspond 
a aucune transparence et le blanc complet correspond a une transparence totale. 

• Les elements Startlntensity et Endlntensity doivent contenir la valeur 100. 
Lexemple suivant met en oeuvre ces principes. 

rem Codel0-02 . odg bibli : Degrades Module2 
Option Explicit 

Sub Appl iquerDegradeDeTransparenceO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim monDegrade As New com. sun. star .awt. Gradient 

Dim nomDegrade As String, n As Long, servGrad As Object 
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monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi n2") 
maForme = Fi ndObjectByName(maPage , "F2") 
With monDegrade ' construction du degrade 

.Style = com. sun. star. awt . Gradi entStyl e . ELLIPTICAL 

.StartColor = transparence(20) 

.EndColor = transparence(80) 

.XOffset = 50 

.YOffset = 50 

.Angle = 200 '20 degres, sens anti-horaire 
.Border = 5 

.Startlntensity = 100 ' toujours 100 
.Endlntensity = 100 ' toujours 100 
End With 

servCrad = monDocument. createlnstance( 

"com . sun . star .drawn ng . TransparencyCradi entTabl e") 

' trouver un nom pas encore utilise, pour ce degrade 
nomDegrade = "zzz" 
n = 1 

Do While servCrad. hasByName (nomDegrade & n) 

n = n+1 
Loop 

MsgBox("Insertion du degrade nomme : " & nomDegrade & n) 
servCrad . insertByName(nomDegrade & n, monDegrade) 
1 utiliser ce degrade 

maForme . Fil UransparenceGradientName = nomDegrade & n 
End Sub 



' renvoie un gris correspondant au pourcentage demande 
Function transparence(pourCent As Long) As Long 
Dim composante As Integer 
if pourCent < 0 then 

composante = 0 
elseif pourCent > 100 then 

composante = 255 
el se 

composante = 255.0 * pourCent / 100.0 

end i f 

transparence = RCB(composante, composante, composante) 

End Function 

Pour remplir les elements StartColor et EndColor, nous utilisons la fonction utili- 
taire transparence afin de se rapprocher de ce qu'offre l'interface utilisateur. Nous 
lui donnons en argument le pourcentage de transparence, et elle nous renvoie la 
valeur de gris correspondante. 
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La methode createlnstance du document permet d'invoquer le service dormant 
acces au conteneur des degrades de transparence. Ce conteneur n'est accessible que 
par le nom de ses contenus. La methode hasByName du conteneur renvoie True si un 
nom existe dans le conteneur. Nous utiliserons un nom quelconque complete par un 
nombre pour rechercher un nom inexistant. La methode i nsertByName du conteneur 
nous permet d'inserer notre degrade avec le nom obtenu. 

II est parfaitement possible de combiner sur une meme forme un degrade de couleur 
et un degrade de transparence. 

Fond hachure 

Hachurer se traduit en anglais par to hatch (a vos souhaits !). Comme pour un 
degrade de couleur, une forme dispose de la propriete FillHatchName, de type 
String, qui indique le nom du modele de hachures, et que nous n'avons pas besoin 
d'utiliser. Nous remplirons directement la propriete Fill Hatch qui contient l'objet 
hachure, une structure decrite dans le tableau 10-12. 

Tableau 10-12 Proprietes de hachure 
Propriete Type Signification 



Style 


Long 


Style de hachure ; constante nommee, voir tableau 10-13. 


Color 


Long 


Couleur des lignes. 


Di stance 


Long 


Ecartement des lignes, en 1/100 de mm. 


Angl e 


Long 


Angle, en 1/10 de degre, n'utiliser que les valeurs positives ; le sens de 
rotation est I'inverse des aiguilles d'une montre. 



Les styles de hachures sont des constantes nominees (tableau 10-13) de la forme : 



com . sun . star . drawi ng . HatchStyl e . SINGLE 



Tableau 10-13 Constantes de style de hachure 





SINGLE 


Une ligne. 


DOUBLE 


Deux lignes perpendiculaires. 


TRIPLE 


Deux lignes perpendiculaires et une ligne en diagonale. 



Les hachures ont un fond transparent si la propriete Fill Background, de type 
Bool ean, vaut Fal se. Si elle vaut True, le fond prendra la couleur indiquee par la pro- 
priete Fi 11 Col or. Dans ce cas, la transparence peut dependre d'un degrade de trans- 
parence. N'oublions pas enfin de changer la propriete Fi 11 Styl e de la forme. 
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rem CodelO-02 . odg bibli : Hachures Modulel 
Option Explicit 

Sub AppliquerHachureO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim hachures As Object 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi n2") 
maForme = Fi ndObjectByName(maPage , "F2") 
hachures = maForme. FillHatch 
With hachures 

.Style = com. sun. star .drawing. HatchStyle. SINGLE 

.Color = RCB(200,0,0) 

.Distance = 500 

.Angle = 250 
End With 

maForme. Fill Hatch = hachures 
maForme. Fill Background = True 

maForme. Fill Style = com. sun. star. drawing. Fill Style. HATCH 
End Sub 

Fond a motif bitmap 

L'API ne permet pas d'ajouter par programmation un nouveau motif bitmap dans un 
document. De plus, les motifs non utilises ne sont pas sauvegardes dans le document. 
Pour utiliser un motif bitmap pour le remplissage d'une forme, il faut done que ce 
meme motif soit deja utilise dans une autre forme. En pratique, la solution est de 
partir d'un document ou modele existant dans lequel on aura manuellement introduit 
les motifs dans des formes. 

Le conteneur de motifs du document est obtenu en invoquant le service 
com. sun. star, drawi ng . Bi tmapTabl e. Un motif bitmap est applique a une forme en 
copiant son nom dans la propriete FillBitmapName et en affectant a la propriete 
Fi 11 Styl e la constante nommee BITMAP. Dans le document exemple, nous avons utilise 
le motif Granit_vert dans une forme d'une page de dessin, afin qu'il reste memorise. 

rem CodelO-02 . odg bibli : Motif bmp Modulel 
Option Explicit 

Sub AppliquerMotifBitmapO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim servMotifs As Object, nomMotif As String, unMotif As String 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi n2") 
maForme = Fi ndObjectByName(maPage , "F2") 
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nomMotif = "Gran-it vert" 

servMotifs = monDocument.createInstance( 

"com . sun . star .drawn ng . Bi tmapTabl e") 

if servMotifs.hasByName (nomMotif) then 
maForme.FillBitmapName = nomMotif 

maForme. Fill Style = com. sun. star. drawing. Fill Style. BITMAP 

else 

MsgBox("Nom de motif inconnu : " & nomMotif, 16) 
end if 
End Sub 

La forme expose plusieurs proprietes qui precisent la maniere d'appliquer le motif sur 
la surface de la forme, voir le tableau 10-14. Ces proprietes remplissent le role des 
parametres de l'interface utilisateur pour le remplissage, onglet Remplissage. 

Tableau 10-14 Proprietes d'application de motif 



Fi 1 1 Bi tmapLogi cal Si ze 


Boolean 


True signifie que Fi 1 1 Bi tmapSi zeX et Y sont en pourcen- 

tage relatif a la taille du bitmap original. 

Fal se signifie que ces dimensions sont en 1/100 de mm. 


FillBitmapOffsetX 


Long 


Decalage horizontal du debut de motif, en pourcentage de la lar- 
geur du bitmap original. 


FillBitmapOffsetY 


Long 


Decalage vertical du debut de motif, en pourcentage de la hauteur 
du bitmap original. 


Fi 1 1 Bi tmapPosi ti onOf f setX 


Long 


Decalage horizontal d'une ligne sur deux, en pourcentage de la 
largeur du bitmap original. 


Fi 1 1 Bi tmapPosi ti onOf f setY 


Long 


Decalage vertical d'une colonne sur deux, en pourcentage de la 
hauteur du bitmap original. 


FillBitmapSizeX 


Long 


Largeur. 


FillBitmapSizeY 


Long Hauteur. 


Fi 11 BitmapMode 


Long 


Methode d'utilisation du motif pour couvrir la surface. Constante 
nommee (voir le tableau 1 0-1 5). 


Fill Bi tmapRectangl ePoi nt 


Long 


Position dans le bitmap utilisee pour le coin haut-gauche. Cons- 
tante nommee (voir le tableau 1 0-1 6). 



Les constantes nominees (tableau 10-15) de FillBitMapMode sont de la forme 
com . sun . star . drawi ng . Bi tmapMode . REPEAT 
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Tableau 10-15 Constantes de mode d'utilisation du motif 



Constante Methode 


REPEAT 


Repeter le motif. 


STRETCH 


Etaler le motif. 


NO_REPEAT 


Plaquer tel quel. 



Les constantes nominees (tableau 10-16) de FillBitmapRectanglePoint sont de la 
forme : 

com. sun . star .drawn ng . Rectangl ePoi nt . LEFT_TOP 

Tableau 10-16 Constantes de position dans un rectangle 



Constante Position 


LEFT_TOP 


Coin en haut a gauche. 


MIDDLE_TOP 


En haut et au milieu. 


RIGHT_TOP 


Coin en haut a droite. 


LEFT_MIDDLE 


A gauche etau milieu. 


MIDDLE_MIDDLE 


Centre. 


RIGHT_MIDDLE 


A droite et au milieu. 


LEFT_BOTTOM 


Coin en bas a gauche. 


MIDDLE_BOTTOM 


En bas et au milieu. 


RIGHT_BOTTOM 


Coin en bas a droite. 



L'ombre d'unc forme 

L'ombre portee par une forme est definie par plusieurs proprietes, listees au 
tableau 10-17. 

Tableau 10-17 Proprietes d'ombre de forme 



Shadow 


Boolean 


True pour activer l'ombre. 


ShadowColor 


Long 


Couleur de l'ombre. 


ShadowTransparence 


Integer 


Pourcentage de transparence, entre 0 (opaque) et 100 (trans- 
parent). 


ShadowXDi stance 


Long 


Decalage horizontal de l'ombre, mesure par rapport au bord 
gauche de la forme. En 1/100 de mm, positif vers la droite. 


ShadowYDi stance 


Long 


Decalage vertical de l'ombre, mesure par rapport au bord du 
haut de la forme. En 1 /1 00 de mm, positif vers le bas. 
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Les decalages de l'ombre peuvent avoir une valeur negative. 

rem CodelO-02 . odg bibli : Proprietes Module3 
Option Explicit 

Sub OmbreFormeO 

Dim monDocument As Object, maPage As Object, maForme As Object 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi n3") 
maForme = FindObjectByName(maPage, "F5") 

With maForme 

.ShadowColor = RGB (100 , 100 , 100) 
.ShadowTransparence = 30 

. ShadowXDi stance = -1000 ' ombre portee a gauche 

. ShadowYDi stance = 300 ' et vers le bas 

.Shadow = true 
End With 
End Sub 

Angle de rotation de la forme 

Cette propriete effectue une rotation de la forme. 
maForme. RotateAngle = 2500 ' 25 degres 

L'angle est exprime en 1/100 de degre par rapport a l'horizontale. N'utilisez que des 
valeurs positives, qui correspondent au sens inverse des aiguilles d'une montre. 

Cisaillement de la forme 

Cet effet transforme un rectangle en parallelogramme. Pour un autre type de forme, 
l'effet est equivalent. 

maForme. ShearAngle = 3000 ' 30 degres de cisaillement 

L'angle est exprime en 1/100 de degre par rapport au cote vertical d'un rectangle ; 
une valeur positive correspond au sens des aiguilles d'une montre. 
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Ecrire un texte dans une forme 

Le texte d'une forme peut etre gere dans sa totalite, mais il est aussi possible de 
modifier le formatage de certains caracteres du texte. 

Gestion globale du texte 

Pour un usage simple, on peut se contenter de l'objet Text expose par la forme. 
L'ensemble du texte est disponible en lecture et en ecriture dans la propriete Stri ng, de 
type Stri ng, de l'objet texte. Cet exemple ecrit un texte dans une forme nommee Fl. 

rem CodelO-03 .odg bibli : Texte Modulel 
Option Explicit 

Sub Ecri reTexteCl obal () 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim monTexte As Object 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi nl") 
maForme = Fi ndObjectByName(maPage , "Fl") 

monTexte = maForme. Text 
monTexte . String = "Bonjour !" 
End Sub 

On peut appliquer au texte dans son ensemble la plupart des proprietes de formatage 
des caracteres detaillees au chapitre 8, a la section « Formatage local des caracteres ». 
Les proprietes CharBackColor, CharBackTransparent, CharCaseMap et 
CharStyleName ne sont pas supportees dans Draw. 

II suffit de reprendre dans les exemples pour Writer la ligne de formatage en rempla- 
cant monCurseur par monTexte. A titre d'exemple, ce codage modifie la taille des 
caracteres du texte de la forme. 

rem CodelO-03 .odg bibli : Texte Module2 
Option Explicit 

Sub TaillePoliceTexte() 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim monTexte As Object, taille As Long 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi nl") 
maForme = Fi ndObjectByName(maPage , "Fl") 
monTexte = maForme. Text 
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Taille = InputBox("Tai 1 1 e de la police (en points)") 
if Taille > 0 then 

monTexte .Char Height = Taille 
end if 
End Sub 

Notez que pour definir le formatage de caractere sur une forme qui n'a pas encore 
recu de texte, vous devez utiliser le curseur d'ecriture. 



Position du texte dans la forme 

Elle depend des proprietes indiquees au tableau 10-18, qui correspondent aux para- 
metres du panneau contextuel Texte, onglet Texte reproduit sur la figure 10-1. 



Figure 10-1 

Panneau contextuel Texte 
sur une forme 




: i 


J Annulet | 


Aide 


Retablir 











Tableau 10-18 Proprietes de position du texte 
tion 



TextHorizontal Adjust 


Long 


Point d'origine de la position horizontale. Constante nommee, voir 
tableau 10-19. 


TextVerti cal Adjust 


Long 


Point d'origine de la position verticale. Constante nommee, voir 
tableau 10-20. 


TextLef tDi stance 


Long 


Espacement du cadre a gauche du texte. 


TextRi ghtDi stance 


Long 


Espacement du cadre a droite du texte. 


TextUpperDi stance 


Long 


Espacement du cadre en haut du texte. 
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Tableau 10-18 Proprietes de position du texte (suite) 



TextLowerDi stance 


Long 


Espacement du cadre en bas du texte. 


TextFitToSize 


Long 


Adaptation de la police du texte dans un changement de taille de la forme. 
Constante nommee, voir tableau 10-21 


TextContour Frame 


Boolean 


True pour adapter le texte au contour. 



L'ancrage du texte est la combinaison des proprietes TextHorizontal Adjust et 
TextVerti calAdjust. Elles recoivent respectivement des constantes nominees de la 
forme : 

com. sun . star . drawi ng .TextHori zontal Ad j ust . LEFT 
com. sun. star . drawn ng .TextVerti calAdjust .TOP 

Tableau 10-19 Constantes de position horizontale du texte 



LEFT 


Horizontalement : a gauche. 


CENTER 


Horizontalement : au centre. 


RIGHT 


Horizontalement : a droite. 


BLOCK 


Horizontalement : etale 


Tableau 10-20 Constantes de position verticale de texte 


Constante Position du texte 


TOP 


Verticalement : en haut 


CENTER 


Verticalement : au centre 


BOTTOM 


Verticalement : en bas 


BLOCK 


Verticalement : etale 



La propriete TextFi tToSi ze recoit une constante nommee de la forme : 
| com . sun . star .drawn ng .TextFi tToSi zeType . PROPORTIONAL 

Les differentes valeurs sont listees au tableau 10-21. Cependant, seules les valeurs 
NONE et PROPORTIONAL semblent avoir une utilite, contrairement a ce que dit la docu- 
mentation API. 
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Tableau 10-21 Constantes d'adaptation du texte au cadre 





NONE 


Pas d'adaptation. 


PROPORTIONAL 


La largeur de la police est modifiee pour que la plus longue ligne du 
texte corresponde a la largeur du rectangle englobant la forme. La hau- 
teur de la police depend de la hauteur du rectangle englobant. 


ALLLINES 


Meme effet que PROPORTIONAL. 


RESIZEATTR 


Pas d'effet visible d'adaptation. 



Texte anime 

Ces proprietes, qui s'appliquent a l'ensemble du texte de la forme, sont disponibles 
pour Draw mais en pratique utilisees dans le contexte d'une presentation Impress 
visualisee avec un ordinateur. Elles sont listees dans le tableau 10-22. 



Tableau 10-22 Proprietes d'animation du texte 



TextAni mati onKi nd 


Long 


Genre d'animation ; constante nommee, voir 
tableau 10-23. 


TextAni mati onDi recti on 


Long 


Sens du defilement du texte ; constante nommee, voir 
tableau 10-24. 


TextAni mati onAmount 


Integer 


Nombre de pixels de decalage a chaque pas du 
defilement. 


TextAni mati onDel ay 


Integer 


Nombre de millisecondes entre chaque pas du 
defilement, ou pour chaque etape du clignotement. 


TextAni mati onCount 


Integer 


Nombre de repetitions de I'animation. Zero, s'il n'y a pas 
de limitation. 


TextAni mati onStartlnsi de 


Boolean 


True pour que le texte soit visible au debut de 
I'animation. 


TextAni mati onStopInsi de 


Bool ean True pour que le texte soit visible a la fin de 
I'animation. 



Le tableau 10-23 liste les valeurs possibles de la propriete TextAni mati onKind. Les 
constantes nominees sont de la forme : 



com . sun . star . d rawi ng . TextAni mati onKi nd . SCROLL 
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Tableau 10-23 Constantes de genre d'animation du texte 



Constante Resultat 


NONE 


Pas d'animation. 


BLINK 


Texte clignotant. 


SCROLL 


Texte defilant. 


ALTERNATE 


Texte defilant alternativement dans un sens puis dans I'autre. 


SLIDE 


Le texte apparaTt en defilant et s'arrete une fois en place. La propriete 
TextAnimationCount doit etre a zero. 



Le tableau 10-24 indique les differentes directions de defilement. Ces constantes 
nominees sont de la forme : 

| com. sun . star .drawn ng .TextAnimationDi recti on . UP 

Tableau 10-24 Constantes de direction de defilement 



LEFT 


Vers la gauche. 


RIGHT 


Vers la droite. 


UP 


Vers le haut. 


DOWN 


Vers le bas. 



Nous laisserons le lecteur s'amuser a tester toutes ces possibilites avec une macro. 



Utilisation d'un curseur d'ecriture 

Pour formater certains caracteres du texte differemment des autres, nous aurons besoin 
d'un curseur d'ecriture qui permet de pointer une zone dans le texte. Nous ne develop- 
perons pas ici cette methode, qui est expliquee au chapitre 8, aux sections « Le curseur 
d'ecriture », « Inserer du texte » et « Formatage local des caracteres ». Le curseur d'ecri- 
ture obtenu est un simple curseur de caractere, il ne reconnait ni les mots, ni les 
phrases. Les proprietes de caractere CharBackColor, CharBackTransparent, 
CharCaseMap et CharStyl eName ne sont pas supportees dans Draw. 

Dans cet exemple, nous allons modifier le texte « Bonjour ! » que nous avons ecrit 
precedemment dans la forme Fl. 

rem CodelO-03 . odg bibli : Texte Module3 
Option Explicit 



Sub ManipulerTexteQ 



Les documents Draw et Impress 

Chapitre 10 



Sub Mani pul erTexte() 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim monTexte As Object, monCurseur As Object, pargr As String 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi nl") 
maForme = FindObjectByName(maPage, "Fl") 

pargr = com . sun . star . text . Control Character . PARAGRAPH_BREAK 

monTexte = maForme. Text 

monCurseur = monTexte. createTextCursor 

With monCurseur 

.gotoStart(fal se) ' ne pas oublier de positionner le curseur 

.goRight(l, true) ' sel ectionner le ler caractere 

.CharColor = RCB(255,0,0) ' peindre en rouge 

.CharWeight = com . sun . star . awt . FontWeight . BOLD 

. gotoEnd(fal se) ' aller en fin de texte 

.goLeft(l, false) ' se placer avant le point d'exclamation 
monTexte. insertString(monCurseur, "tout le monde ", false) 
. gotoEnd(fal se) ' aller en fin de texte 
' inserer une fin de paragraphe 

monTexte. insertControlCharacter(monCurseur, pargr, false) 
.CharHeight = 16 ' changer la taille a parti r d'ici 
. CharFontName = "Arial" ' changer la police 
.CharUnderlineHasColor = false 

. CharUnderl i ne = com . sun . star . awt . FontUnderl i ne . DOUBLE 
monTexte. insertString(monCurseur, "OpenOffice.org", false) 

End With 

End Sub 

Pour eviter des problemes d'initialisation, positionnez le curseur en debut ou fin de 
texte, juste apres sa creation. Vous avez remarque l'insertion d'un paragraphe. Effec- 
tivement, le curseur supporte un service restreint de paragraphe. Les proprietes 
offertes sont : 

• ParaAdjust 

• ParaTopMargi n 

• ParaBottomMargi n 

• ParaLeftMargi n 

• ParaRi ghtMargi n 

• ParaFi rstLi nelndent 

• ParaLastLi neAdjust 

• ParaLi neSpaci ng 

• ParaTabStops 



Manipuler les documents OpenOffice.org 

Troisieme partie 



Les differentes formes 

Nous avons vu plus haut comment ajouter une forme sur une page. Le parametre de la 
methode createlnstance precise quel type de forme doit etre cree. Le tableau 10-25 
liste les principaux types, qui sont des chaines de caracteres representant des noms de 
service. Leur nom complet est de la forme (il faut respecter la casse) : 

com . sun . star . d rawi ng . Rectangl eShape 

Tableau 10-25 Noms des formes 



Rpr1"3nnl pShanp 

i \ t v_ i_ ci i i y i c ji i a |~> vi 


Rprtannlp nil rarrp 

1 \CV_ LLI 1 1 U 1 C L/U V.UIIC 


FT 1 H n^P^hanp 

l_l 1 1 p jC Jl la[JC 


FllirKP mi rprrlp 

LIIIIJ3C UU LCI LIC. 


1 inpShanp 

i i i ic ji i cl yj vZ 


1 innp rlroitp 

LIUIIC Ul ullC 


Pnl \/l nnp^hpinp 

i \j i y i i i ic ji icipc 


1 innp hriepp 

li y 1 ic ui 1 jcc. 


Pol vPol vflonSh^np 

i u i y i vj i y yui i ji icipc 


Pnlvnnnp 

1 L/l f ULfl IC 


Tp Yt^hanp 

1 CA L Jlla^C 


Texte 


V.U|J L 1 Ul 1 JI IU|JC 


Ftinupttp 

l_ UUUC LLC 


ConnectorShape 


Connecteur. 


MeasureShape 


Ligne de cote. 


OpenBezi erShape 


Courbe de Bezier ouverte. 


ClosedBezierShape 


Courbe de Bezier fermee. 


Pol y Pol ygonBezi erShape 


Polygone de Bezier. 


GraphicObject Shape 


Contient une image, voir la section « Les images ». 


CroupShape 


Contient des formes groupees, voir la section « Grouper des formes ». 


Control Shape 


Aspect forme d'un controle de formulaire. Voir le chapitre 13. 


0LE2Shape 


Objet 0LE2. 


PI ugi nShape 


Objet plug-in. 


AppletShape 


Objet applet Java 


PageShape 


Vignette d'une diapo Impress, utilise dans les feuilles de notes Impress. 


Shape3DScene0bject 


Forme 3D. 


Tabl eShape 


Tableau. 


CustomShape 


Forme composee (symboles Frimousse, Soleil, Lune, etc.). 



Les derniers types cites dans le tableau 10-25 sont peu (voire pas) documentes, ou 
difficiles a utiliser depuis l'API. 
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Le rectangle et le carre 

Le rectangle a deja ete utilise quand nous avons cree une forme. Si la hauteur est 
egale a la largeur, evidemment vous obtenez un carre. 

La propriete CornerRadi us, de type Long, indique le rayon, mesure en 1/100 de mm, 
du quart de cercle effectue a chaque coin. Une valeur nulle produit un rectangle ordi- 
naire, une autre valeur produit un rectangle aux coins arrondis. 

L'ellipse et le cercle 

Si la hauteur de l'ellipse est egale a sa largeur, vous obtenez un cercle. 

La propriete Ci rcl eKi nd, de type Long, permet d'obtenir differentes variantes d'ellipse, 
listees au tableau 10-26. Cette propriete recoit une constante nommee de la forme : 

com . sun . star . drawi ng . Ci rcl eKi nd . SECTION 

Tableau 10-26 Constantes de variante d'ellipse 



FULL 


Disque. 


SECTION 


Tranche de camembert. 


CUT 


Segment de cercle delimite par Tare de cercle et sa corde. 


ARC 


Arc de cercle. 



La figure 10-2 represente les differentes formes possibles. 



Figure 10-2 

Les variantes d'ellipse 



o 





FULL SECTION CUT ARC 



Le positionnement de Fare de cercle dans les variantes depend de deux autres pro- 
prietes, de type Long : 

• Ci rcl eStartAngl e est Tangle initial de Fare, 

• Ci rcl eEndAngl e est Tangle terminal de Fare. 

Les angles sont mesures en 1/100 de degre, valeurs positives dans le sens inverse des 
aiguilles d'une montre. La position zero de Tangle est l'horizontale, avec le centre de 
rotation situe a gauche de l'arc. 
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Le texte 

La forme de type texte peut etre dessinee avec un contour apparent, ce qui donne un 
cadre. Dans ce cas, il est possible de le forcer a s' adapter au texte qu'il contient, grace 
aux proprietes listees au tableau 10-27. 



Tableau 10-27 Proprietes d'adaptation automatique du cadre 



Propriete 


Type 


Signification 


TextAutoGrowHei ght 


Bool ean 


True pour que la hauteur du cadre s'adapte au texte. 


TextMaxi mumFrameHei ght 


Long 


Hauteur maximale autorisee, en 1/100 de mm. 


TextMi ni mumFrameHei ght 


Long 


Hauteur minimale autorisee, en 1/100 de mm. 


TextAutoGrowWi dth 


Boolean 


True pour que la largeur du cadre s'adapte au texte. 


TextMaxi mumFrameWi dth 


Long 


Largeur maximale autorisee, en 1/100 de mm. 


TextMi ni mumFrameWi dth 


Long 


Largeur minimale autorisee, en 1/100 de mm. 



L'equivalent sur l'interface utilisateur se trouve dans le panneau Position et taille, onglet 
Position et taille, cases a cocher Adapter la largeur au texte et Adapter la hauteur au texte. 

Dans le document du Zip telechargeable nous avons mis dans la page Dessin2 une 
forme texte F5 avec un cadre apparent. Cet exemple montre l'effet sur la largeur, 
selon les textes a afficher. 



rem Codel0-03 .odg bibli : Texte Module4 
Option Explicit 

Sub EnveloppeElastiqueO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim nouvTxt As String, souhaitAuto As Long 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi n2") 

maForme = Fi ndObjectByName(maPage , "F5") 

Do 

souhaitAuto = MsgBox("Largeur automatique ?", 3) 

if souhaitAuto = 2 then exit do ' reponse = Annul er 

maForme. TextAutoGrowWi dth = (souhaitAuto = 6) 

maForme . Stri ng = InputBox("Nouveau texte", "", maForme . Stri ng) 
Loop 
End Sub 



La ligne simple 

Rien nest plus simple que de definir une ligne simple : la position et les dimensions 
de la forme suffisent. Cependant, il existe une deuxieme methode pour la definir, en 
considerant quelle n'est rien d'autre qu'une ligne brisee a un seul segment. 
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Les proprietes de contour s'appliquent a la ligne (quelle soit simple, brisee, ou autre). 
Les extremites d'une ligne (fleche, carre, rond) sont des poly-polygones de Bezier 
rattaches au debut et a la fin de la ligne. Ces objets sont accessibles par les proprietes 
LineStart et LineEnd respectivement. II n'est pas possible d'obtenir des extremites 
predefinies, au contraire de l'interface utilisateur. 

Notez enfin qu'il est parfaitement possible d'affecter un texte a une ligne, et ajuster la 
position du texte pour le placer au-dessus ou au-dessous de la ligne. 



La ligne brisee 

Une ligne brisee est decrite a partir des coordonnees des points extremites des seg- 
ments de droite successifs. Chaque point est defini avec une structure Poi nt (voir le 
tableau 10-3). A la serie de points correspondra un tableau de structures. 

Nous devons d'abord ajouter la ligne brisee a la page, sans indication de position ni 
dimension. Ensuite seulement nous affecterons a la forme les coordonnees de points. 

rem CodelO-04 . odg bibli : Polygenies Module2 
Option Explicit 

Sub LigneBriseeO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim lesPoints(8) As New com. sun. star .awt. Point 

monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Pol ygones") 
maForme = monDocument . createlnstance(_ 

"com . sun . star . drawi ng . Pol yLi neShape") 



lesPoints(O) 


.X 




4000 


lesPoints(O) 


.Y 




2000 


lesPoints(l) 


.X 




4500 


lesPoints(l) 


.Y 




4000 


lesPoints(2) 


.X 




11500 


lesPoints(2) 


.Y 




8000 


lesPoints(3) 


.X 




12000 


lesPoints(3) 


.Y 




10000 


lesPoints(4) 


.X 




16000 


lesPoints(4) 


.Y 




4550 


lesPoints(5) 


.X 




8000 


lesPoints(5) 


.Y 




9000 


lesPoints(6) 


.X 




9000 


lesPoints(6) 


.Y 




11500 


lesPoints(7) 


.X 




22000 


lesPoints(7) 


.Y 




9500 


lesPoints(8) 


.X 




11000 


lesPoints(8) 


.Y 




4000 
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maPage . add(maForme) 

maForme . Li neWi dth = 80 

maForme . Pol yPol ygon = Array(lesPointsO) 

End Sub 

La maniere d'affecter les points est particuliere : 1'utilisation de la fonction Basic 
Array () constitue un tableau dont les elements sont les arguments. Ici, il y a un seul 
element, lesPointsO qui est lui-meme notre tableau de points. La raison d'etre de 
cette construction est que la ligne brisee utilise des mecanismes qui servent aussi a 
dessiner des polygones multiples. La ligne brisee est consideree comme un polygone 
unique et ouvert. La forme resultante est entierement dependante des points succes- 
sifs, comme on le voit sur la figure 10-3. 

Figure 10-3 \ 

Une ligne brisee \ 



Nous avons dit que la ligne simple etait un cas particulier de la ligne brisee. En effet, 
pour la construire il suffirait de reprendre le code ci-dessus avec le tableau 
lesPointsO reduit a deux elements, et de creer la forme avec le service LineShape 
au lieu de Pol yLi neShape. 

Le polygone 

Reprenons l'exemple de la ligne brisee. II suffit d'utiliser le service Pol y Pol ygonShape 
au lieu du service Pol yLi neShape pour obtenir un polygone ferme. Le point initial et 
le point final sont automatiquement relies par un segment de droite. 

rem CodelO-04 . odg bibli : Polygones Module3 
Sub unPolygoneO 

partie identique ------ 

maForme = monDocument.createInstance(_ 

"com . sun . star . drawn ng . Pol yPol ygonShape" ) 

partie identique ------ 

Le dessin obtenu, reproduit a la figure 10-4, est etonnant en ce qui concerne le rem- 
plissage. 



Les documents Draw et Impress 

Chapitre 10 



Figure 10-4 

Polygone ferme 




La figure contient des trous lorsque les lignes se croisent. II s'agit bien de trous, car 
une autre forme en arriere-plan apparaitrait dans ces zones. Quel est le principe de 
« creation » de ces trous ? OpenOffice.org part d'un point a l'exterieur du dessin, et 
analyse par exemple de gauche a droite. A partir de la premiere ligne du dessin ren- 
contree, OpenOffice.org decide qu'il se trouve sur la surface du dessin. S'il rencontre 
une autre ligne du meme dessin, il decide qu'il vient de passer a l'exterieur. Le pro- 
cessus se repete a chaque ligne traversee. Les trous sont les zones considerees comme 
exterieures au polygone ferme. 

Nous pouvons done creer des formes sans trous ou avec trous, mais pas n'importe 
lesquels : nous ne pouvons pas creer un trou sans aucun point commun avec le con- 
tour englobant. Pour plus de liberte nous avons besoin du poly-polygone. 

Le poly-polygone 

Le poly-polygone consiste a utiliser plusieurs polygones dans la suite de points defi- 
nissant la forme. Certains polygones peuvent etre inclus a l'interieur d'autres. 
Cependant, comme ils sont considered comme appartenant a la meme forme, l'algo- 
rithme de decision surface/trou s'appliquera a chaque ligne rencontree. 

Nous allons dessiner un rectangle avec deux trous en triangles opposes par un 
sommet. Cette fois-ci la propriete Poly Polygon recevra un tableau de deux elements, 
le premier etant le rectangle, le deuxieme etant un polygone croise. 

rem CodelO-04 . odg bibli : Polygones Module4 
Option Explicit 

Sub GruyereAbstraitO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim enveloppe(3) As New com . sun . star . awt . Poi nt 
Dim triangles (3) As New com . sun . star . awt . Poi nt 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Pol ygones") 
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maForme = monDocument.createInstance(_ 

"com . sun . star .drawn ng . Pol y Pol ygonShape") 
enveloppe(O) .X = 4500 
envel oppe(O) . Y = 3500 
enveloppe(l) .X = 4500 
envel oppe(l) . Y = 9500 
enveloppe(2) .X = 19000 
envel oppe(2) . Y = 9500 
enveloppe(3) .X = 19000 
envel oppe(3) . Y = 3500 
tn'angles(O) .X = 6000 
tn'angles(O) . Y = 5000 
tn'angles(l) .X = 17000 
tn'angles(l) .Y = 9000 
triangles(2) .X = 17000 
tn'angles(2) .Y = 5000 
tn'angles(3) .X = 6000 
tn'angles(3) . Y = 9000 
maPage . add (maForme) 
maForme . Li neWi dth = 80 

maForme. Pol yPolygon = Array(enveloppe() , trianglesO) 

End Sub 

La forme resultante est reproduite a la figure 10-5. Dans le document du Zip telechar- 
geable, la forme se superpose a un dessin existant, afin de mettre en valeur les trous. 



Figure 10-5 

Poly-Polygone troue 




Le connecteur 

Les proprietes de ligne simple sont aussi disponibles pour le connecteur. Les sym- 
boles eventuels (fleche, carre, rond) a une extremite du connecteur sont des poly- 
polygones de Bezier rattaches au debut et a la fin de la ligne. Ces objets sont accessi- 
bles par les proprietes LineStart et LineEnd. 

Les principales proprietes specifiques du connecteur sont listees au tableau 10-28. 
Les huit premieres correspondent au panneau Connecteur du menu contextuel, dans 
l'interface utilisateur. 
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Tableau 10-28 Proprietes d'un connecteur 



EdgeKi nd 


Long 


Type de connecteur ; constante nommee, voir tableau 10-29. 


EdgeLinelDelta 


Long 


Decalage de ligne 1, en 1/100 de mm. 


EdgeLine2De"lta 


Long 


Decalage de ligne 2, en 1/100 de mm. 


EdgeLine3De"lta 


Long 


Decalage de ligne 3, en 1/100 de mm. 


EdgeNodelHorzDi st 


Long 


Interligne, debut horizontal, en 1/100 de mm. 


EdgeNodelVertDist 


Long 


Interligne, debut vertical, en 1/100 de mm. 


EdgeNode2HorzDi st 


Long 


Interligne, fin horizontale, en 1/100 de mm. 


EdgeNode2VertDist 


Long 


Interligne, fin verticale, en 1/100 de mm. 


StartShape 


Object 


La forme a laquelle le debut du connecteur est connecte ; null si 
le debut du connecteur n'est pas connecte. 


StartGl uePoi ntlndex 


Long 


Rang du point de colle auquel le debut du connecteur est 
connecte. 


StartPosition 


Object 


Coordonnees du debut du connecteur, en1/1 00 de mm ; struc- 
ture Poi nt, voir le tableau 10-3. En lecture seule si le connec- 
teur est connecte. 


EndShape 


Object 


Comme StartShape, pour la fin du connecteur. 


EndCT uePoi ntlndex 


Long 


Comme StartGl uePoi ntlndex pour la fin du connecteur. 


EndPosition 


Object 


Comme StartPosi ti on, pour la fin du connecteur. 



Les constantes nominees de la propriete EdgeKi nd, listees au tableau 10-29, sont de 
la forme : 

| com . sun . star . drawi ng . ConnectorType . STANDARD 

Tableau 10-29 Constantes de type de connecteur 
Type de connecteur 



STANDARD 


Standard. 


CURVE 


Incurve. 


LINE 


Direct. 


LINES 


Lineaire. 



Nous donnons un exemple d'utilisation de connecteur dans la section « Collages (les 
points de colle) ». 
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L'etiquette 

Ce type de forme n'est pas present par defaut dans la barre de dessin. II ne faut pas le 
confondre avec le choix de formes appele « Legendes » qui renvoie a des formes du 
type CustomShape et que nous ne savons pas programmer. Personnalisez la barre 
d'outils en inserant la commande Legende dans la categorie Dessin. 

Le tableau 10-30 liste les proprietes specifiques essentielles d'une etiquette. Cer- 
taines proprietes se retrouvent dans le panneau contextuel Position et taille, onglet 
Legende. Notez que la propriete CornerRadius, deja vue pour le rectangle, permet 
d'arrondir les angles du cadre de l'etiquette. 

Les symboles eventuels (fleche, carre, rond) a une extremite du trait indicateur sont 
des poly-polygones de Bezier rattaches au debut et a la fin de la ligne. Ces objets sont 
accessibles paries proprietes LineStart et LineEnd. 

Tableau 10-30 Proprietes d'une etiquette 
Signification 



Capti onPoi nt 


Object 


Position du point indique par l'etiquette. Structure Poi nt 
(voir le tableau 10-3). 


CaptionType 


Integer 


Type du trait indicateur, constante nommee, (voir le tableau 
10-31). 


CaptionCap 


Long 


Ecart entre le trait indicateur et le cadre de l'etiquette, 
en 1/100 de mm. 


Capti onlsFi xedAngl e 


Bool ean 


True pour imposer Tangle de la ligne avec 
Capti onAngle. 

Fal se pour laisser ['application choisir Tangle optimal. 


CaptionAngl e 


Long 


Angle du trait indicateur. 


Capti onlsEscapeRel ati ve 


Bool ean 


True si la position de depart du trait indicateur est expri- 
mee par Capti onEscapeRel ati ve ; 
Fal se si elle est exprimee par 
Capti onEscapeAbsol ute. 


Capti onEscapeRel ati ve 


Long 


Position relative au coin haut-gauche de l'etiquette, expri- 
mee en 1 /1 00 de pourcentage de la largeur ou la hauteur 
de celle-ci. 

Par exemple, 5000 correspond a 50,00% de la largeur ou de 
la hauteur. 


Capti onEscapeAbsol ute 


Long 


Position relative au coin haut-gauche de l'etiquette, expri- 
mee en 1/100 de mm. 


Capti onEscapeDi recti on 


Long 


Direction du trait indicateur, constante nommee (voir le 
tableau 10-32). 
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Tableau 10-30 Proprietes d'une etiquette (suite) 



Propriete 


Type 


Signification 


CaptionlsFitLineLength 


Boolean 


True pour laisser I'application choisir la longueur optimale 






du premier segment du trait indicateur ; 






Fal se si la longueur est imposee par 






CaptionLi neLength. 


CaptionLi neLength 


Long 


Longueur du premier segment du trait indicateur, 
en 1/100 de mm. 



Le type de trait indicateur, decrit au tableau 10-31, est une constante nommee de la 
forme : 



com . sun . star . drawi ng . Capti onType . connector 

Tableau 10-31 Type de trait indicateur 



Constante Type de trait 


straight 


Ligne droite. 


angl ed 


Ligne en angle. 


connector 


Ligne en angle flechie. 



La direction du trait indicateur est realisee differemment de ce qui est visible dans le 
panneau d'interface utilisateur. Les valeurs possibles sont listees au tableau 10-32. 
Les constantes nominees sont de la forme : 



com . sun . star .drawi ng . Capti onEscapeDi recti on . horizontal 



Tableau 10-32 Direction du trait indicateur 



Constante Direction 


hori zontal 


Horizontale. 


vertical 


Verticale. 


auto 


Optimale. 



La ligne de cote 

Le tableau 10-33 liste les proprietes specifiques essentielles d'une ligne de cote. La 
plupart ont un equivalent dans le panneau contextuel Cotation de l'interface utilisa- 
teur. Toutes les longueurs et distances sont exprimees en 1/100 de mm sur la page de 
dessin. Faites des essais sur diverses lignes de cotes pour visualiser les effets (voir le 
Zip telechargeable, Codel0-03.odg, bibliotheque Cotations). 
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Tableau 10-33 Proprietes d'une ligne de cote 



MeasureHel pLi nelLength 


Long 


Longueur du repere gauche. 


MeasureHel pLi ne2Length 


Long 


Longueur du repere droit. 


MeasureHel pLi neDi stance 


Long 


Ecart des reperes. 


MeasureHel pLi neOverhang 


Long 


Depassement des reperes. 


MeasureLi neDi stance 


Long 


Ecart des lignes. 


MeasureTextHorizontal Position 


Long 


Position horizontale du texte, constante nommee, 
voir tableau 10-34. 


MeasureTextVertical Position 


Long 


Position verticale du texte, constante nommee, voir 
tableau 10-35. 


MeasureBel owReferenceEdge 


Bool ean 


True pour une ligne de cote sous I'objet. 


Measu reUni t 


Long 


Unite de mesure, voir tableau 10-36. 


MeasureShowUnit 


Boolean 


True pour afficher I'unite de mesure. 


Measu reTextRotate90 


Boolean 


True pour mettre le texte perpendiculaire a la ligne 
de cote. 

La valeur Fal se correspond a la case Parallele au 
repere de I'interface utilisateur. 


Measu reTextUpsi deDown 


Boolean 


True pour tourner le texte de 1 80°. 


MeasureDecimal Places 


Integer 


Nombre de decimales de la mesure. 



Les positions du texte horizontale et verticale sont listees dans les tableaux 10-34 et 
10-35. Les constantes nominees respectives sont de la forme 

I com. sun . star . drawi ng . Measu reTextHorzPos . LEFTOUTSIDE 
com. sun . star .drawi ng . Measu reTextVertPos .WEST 



Tableau 10-34 Position horizontale du texte de cotation 



Constante 


Position 


AUTO 


Automatiquement horizontal. 


LEFTOUTSIDE 


A gauche. 


INSIDE 


Au milieu. 


RIGHTOUTSIDE 


A droite. 


Tableau 10-35 Position verticale du texte de cotation 


Constante 


Position 


AUTO 


Automatiquement vertical. 


EAST 


Au-dessus de la ligne de cote. 
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Tableau 10-35 Position verticale du texte de cotation (suite) 



Constante Position 


BREAKEDLINE 


Au milieu et interrompant la ligne de cote. 


WEST 


Au-dessous de la ligne de cote. 


CENTERED 


Au milieu et interrompant la ligne de cote. 



Tableau 10-36 Unites de mesure d'une cote 



Valeur Unite 


0 


Celle du document. 


1 


mm 


2 


cm 


3 


m 


4 


Km 


5 


Twip 


6 


Pouce 


7 


Pied 


8 


Mile 


9 


Pica 


10 


Point 


11 


Non utilise 


12 


Pourcentage 


13 


/100 de mm 



Les formes de Bezier 

Nous abordons ici des formes complexes, aussi bien a l'interface utilisateur qu'au 
niveau de la programmation. 

A RETENIR Bezier 

Les courbes de Bezier sont des courbes polynomials decrites pour la premiere fois en 1972 par I'inge- 
nieur francais Pierre Bezier (1910-1999) qui les utilisa pour concevoir par ordinateur, des automobiles. 
Les plus importantes courbes de Bezier, sont les cubiques, qui sont utilisees en informatique pour le gra- 
phisme et dans de multiples systemes de traitement d'image tels que PostScript, Metafont et Gimp pour 
dessiner des courbes lisses joignant des points ou des polygones de Bezier. Les fontes TrueType utilisent 
des courbes de Bezier quadratiques plus simples. 
► Source : http://fr.wikipedia.org/ 
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La propriete PolyPolygonBezier est une structure de deux elements : 

• Coordinates est un tableau de tableaux de points, comme nous en avons vu avec 
les lignes brisees, les polygones et poly-polygones ; 

• Flags est un tableau de tableaux d'entiers Long, tel que chaque element corres- 
pond au point de meme index dans Coordinates. 

Chaque element de FT ags contient une constante nommee (tableau 10-37) de la forme : 
com. sun . star . drawi ng . Pol ygonFl ags . NORMAL 

Tableau 10-37 Constantes de point de Bezier 



NORMAL 


Point d'inflexion normal. 


SMOOTH 


Point d'inflexion a jonction lisse. 


SYMMETRIC 


Point d'inflexion a jonction symetrique. 


CONTROL 


Point de controle. 



Lorsque vous editez un point d'une courbe de Bezier, la barre d'outils affiche son 
type : inflexion normale, jonction lisse et jonction symetrique. Un point de controle 
est le point d'extremite de la tangente a la courbe (voir la figure 10-6). Quand vous 
deplacez ce point, un effet de levier modifie la forme de la courbe. 



Figure 10-6 

Courbe et point de controle 




Si nous utilisions seulement des points d'inflexion, nous obtiendrions une ligne 
brisee. Pour dessiner une courbe entre deux points A et B, nous avons besoin 
d'ajouter deux points de controle cA et cB ; la position du point cA regie la tangente 
aboutissant au point A et la position du point cB regie la tangente aboutissant au 
point B. En resume, chaque courbe elementaire est definie par deux points 
d'inflexion situes aux extremites de la courbe et deux points de controle situes en 
dehors de celle-ci. Si le point B est une jonction lisse, la courbe gardera une transi- 
tion douce de part et d'autre du point. 

Pour realiser cela par programmation, il est necessaire de remplir les proprietes 
Coordinates et Flags avec des structures completes, en decrivant les points 
d'inflexion ou de controle rencontres successivement, par exemple : A, cA, cB, B, C. 
N'oubliez pas que les points de controle sont utilises par paires. 
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rem CodelO-04 . odg bibli : Polygenies Module5 
Option Explicit 

Sub LigneBezierO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim lesPoints(7) As New com. sun. star .awt. Point 
Dim 1 eslnfl ex(7) As Long 

Dim BezCoo As New com . sun . star . drawing . Pol yPol ygonBezierCoords 

monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Pol ygones") 
maForme = monDocument. createlnstance( 

"com . sun . star . drawi ng . OpenBezi erShape") 

lesPoints(O) .X = 3500 
lesPoints(O) .Y = 2000 

lesInflex(O) = com. sun . star . drawi ng . Pol ygonFl ags . NORMAL 
lesPoints(l) .X = 4000 
lesPoints(l) .Y = 5000 

leslnflex(l) = com. sun . star . drawi ng . Pol ygonFl ags . CONTROL 
lesPoints(2) .X = 4000 
lesPoints(2) .Y = 5000 

leslnflex(2) = com. sun . star . drawi ng . Pol ygonFl ags . CONTROL 
lesPoints(3) .X = 11500 
lesPoints(3) .Y = 10000 

leslnflex(3) = com. sun . star . drawi ng . Pol ygonFl ags . NORMAL 
lesPoints(4) .X = 17500 
lesPoints(4) .Y = 3000 

leslnflex(4) = com. sun . star . drawi ng . Pol ygonFl ags . CONTROL 
lesPoints(5) .X = -2300 
lesPoints(5) .Y = 3100 

leslnflex(5) = com. sun . star . drawi ng . Pol ygonFl ags . CONTROL 
lesPoints(6) .X = 4500 
lesPoints(6) .Y = 9000 

leslnflex(6) = com. sun . star . drawi ng . Pol ygonFl ags . SMOOTH 
lesPoints(7) .X = 8500 
lesPoints(7) .Y = 12500 

leslnflex(7) = com. sun . star . drawi ng . Pol ygonFl ags . NORMAL 

BezCoo. Coordinates = Array(lesPointsO) 
BezCoo. Flags = Array(lesInflexO) 

maPage .add (maForme) 

maForme. Li neWidth = 80 

maForme. Pol yPolygonBezier = BezCoo 

End Sub 

La forme resultante est reproduite a la figure 10-7. En selectionnant chaque point de 
la forme, vous pourrez faire apparaitre les points de controle et verifier leur position 
(mesuree par rapport a la page entiere). 
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Figure 10-7 

Courbe de Bezier 



Une forme de Bezier fermee s'obtient en invoquant le service ClosedBezierShape au 
lieu de OpenBezierShape. 

Exercice 

Nous laisserons le lecteur s'exercer a obtenir de jolis poly-polygones de Bezier, en s'inspirant du poly- 
polygone ordinaire et en utilisant le service Pol y Pol ygonBezi erShape. 



Collages 

Les points de colle 

Les points de colle d'une forme sont accessibles par sa propriete GluePoints. Cet 
objet est une collection un peu particuliere. On peut obtenir un point de colle en uti- 
lisant son numero d'ordre dans la collection avec la methode getBylndex. Contraire- 
ment aux autres collections indexees, Basic ne peut cependant pas l'indexer comme 
un tableau. De toute facon, l'utilisation de l'index n'est pas judicieuse. En effet, 
l'ajout et la suppression de points de colle peuvent changer l'ordre des autres points 
de colle dans le conteneur. 

Pour identifier chaque point, fourni par defaut ou ajoute, on utilise non pas un nom 
mais un simple entier de type Long. On obtient un point de colle particulier avec la 
fonction getByldentifier, qui prend en argument l'identificateur du point. La 
methode getldenti f i ers de l'objet CI uePoi nts renvoie un tableau des identificateurs 
des points de colle de la forme, l'index du tableau etant celui du conteneur. En balayant 
ce tableau, on peut recuperer l'index d'un point dont on connait l'identificateur. 
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Une forme possede quatre points de colle predefinis, identifies par les numeros 0 a 3. 
Void leur position, par rapport au rectangle englobant la forme : 

• 0 : en haut et au milieu, 

• 1 : a droite et a mi-hauteur, 

• 2 : en bas et au milieu, 

• 3 : a gauche et a mi-hauteur. 

Chaque objet point de colle est une structure CI uePoi nt2 detaillee au tableau 10-38. 

Tableau 10-38 Structure d'un point de colle 



Position 


Object 


Coordonnees du point de colle par rapport a 
Posi ti onAl i gnment ; structure Poi nt (voir le 
tableau 10-3). 


IsRelative 


Boolean 


True si la position est donnee en 1/100 de pourcent. 
Fal se si la position est donnee en 1/100 de mm. 


Post ti onAl i gnment 


Long 


Origine des coordonnees pour le point de colle ; constante nom- 
mee, voir explications ci-apres. 


Escape 


Long 


Direction d'echappement du connecteur colle sur le point ; cons- 
tante nommee, voir explications ci-apres. 


IsllserDef i ned 


Boolean 


True si le point est ajoute par I'utilisateur. 



La Position est exprimee en coordonnees X et Y par rapport a un point origine. Les 
valeurs positives vont vers la droite pour X, vers le bas pour Y, et les valeurs negatives 
vont respectivement vers la gauche et vers le haut (voir figure 10-8). 



Figure 10-8 

Coordonnees relatives centrees 



-5000 



▼Y 









0 I 



X 



Le point origine est precise par la propriete Posi ti onAl i gnment. Les valeurs possi- 
bles sont enumerees dans le tableau 10-39, et se referent au rectangle englobant ; les 
valeurs sont de la forme : 

com . sun . star . d rawi ng . Al i gnment . CENTER 
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Si la propriete IsRelative vaut False, les coordonnees sont exprimees en 1/100 de 
mm, toujours par rapport au point origine. Si la propriete IsRelative vaut True, les 
coordonnees X et Y sont exprimees en centieme de pourcentage de la largeur totale 
pour X et de la hauteur totale pour Y. Par exemple, un point situe sur le cote droit 
d'un rectangle a pour valeur + 50,00 %, ce qui correspond a une valeur de 5000 pour 
X. La figure 10-8 presente les coordonnees par rapport au centre d'un cercle. Le rec- 
tangle englobant est dessine en tirete. 

Tableau 10-39 Constantes de PositionAlignment 





Point d'origine des coordonnees 


T0P_LEFT 


Le coin en haut a gauche. 


TOP 


Le milieu du cote du haut. 


T0P_RIGHT 


Le coin en haut a droite. 


LEFT 


Le milieu du cote de gauche. 


CENTER 


Le centre du rectangle. 


RIGHT 


Le milieu du cote de droite. 


B0TT0M_LEFT 


Le coin en bas a gauche. 


BOTTOM 


Le milieu du cote du bas. 


B0TT0M_RIGHT 


Le coin en bas a droite. 



Les constantes de la propriete Escape, listees au tableau 10-40, sont assez explicites, 
sauf la premiere. Void la forme generale : 

com. sun . star. drawn ng . EscapeDi recti on . RIGHT 

Tableau 10-40 Constantes de Escape 

Constant 



SMART 


A I'initiative d'OpenOffice.org. 


LEFT 


Vers la gauche. 


RIGHT 


Vers la droite. 


UP 


Vers le haut. 


DOWN 


Vers le bas. 


HORIZONTAL 


Horizontalement (gauche ou droite). 


VERTICAL 


Verticalement (haut ou bas). 



Un point de colle pose par programmation peut se situer ailleurs que sur le contour 
de la forme, mais a l'interieur du rectangle englobant. 
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Le code ci-dessous liste les points de colle d'une forme. Dans le document du Zip 
telechargeable, nous avons ajoute et supprime plusieurs points de colle de caracteris- 
tiques variees. Comparez aussi les valeurs d'index et d'identificateur. 

rem CodelO-05 . odg bibli : Collages Modulel 
Option Explicit 

Sub DemoPointsDeColleO 

Li sterPoi ntsdeCol 1 e ("carrel") 
End Sub 

Sub ListerPointsdeColle(nomForme As String) 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim lesPtColle As Object, unPtColle As Object, identites As Object 
Dim x As Long, idPtColle As Long 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi nl") 
maForme = FindObjectByName(maPage, nomForme) 
lesPtColle = maForme. GluePoints 

identites = lesPtColle. Identifiers' methode getldentifiersO 
for x = 0 to lesPtColle. Count -1 
idPtColle = identites(x) 

unPtColle = lesPtColle. getByldentifier(idPtColle) 

MsgBox("Index : " & x & " Identite : " & idPtColle & chr(13) & _ 

"Point rajoute : " & unPtColle. IsUserDefined & chr(13) & _ 

"Alignement : " & unPtColle. PositionAl ignment & chr(13) & _ 

"Relatif : " & unPtColle. IsRelative & chr(13) & _ 

"Echappement : " & unPtCol 1 e . Escape & chr(13) & _ 

"Position X : " & unPtColl e . Position .X & chr(13) & _ 

"Position Y : " & unPtColl e . Position .Y) 

next 

End Sub 



Ajouter un point de colle 

Si vous avez bien compris ce qui precede, l'insertion d'un point de colle vous paraitra 
limpide. Nous allons inserer un point sur le contour d'un cercle. Connaissant le point 
X et le rayon du cercle, le theoreme de Pythagore nous donne la valeur de Y. 

rem CodelO-05 . odg bibli : Collages Module2 
Option Explicit 

Sub AjouterPtColleO 

Dim monDocument As Object, maPage As Object, maForme As Object 

Dim lesPtColle As Object, idPtColle As Long 

Dim unPtColle As New com. sun. star .drawing. GluePoint2 
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Dim unPoint As New com. sun . star . awt . Poi nt 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi nl") 
maForme = Fi ndObjectByName(maPage , "cerclel") 
lesPtColle = maForme. GluePoints 

unPoint.X = 1600 ' 16% du diametre = 32% du rayon de la forme 
1 Le rayon du cercle vaut 50,00% de la hauteur de la forme 
' appliquer le theoreme de Pythagore 
unPo-int.Y = sqr(5000*5000 - unPoint.X * unPoint.X) 

With unPtColle 

.IsRelative = true ' position en pourcentage 

. PositionAl ignment = com. sun. star. drawing. Alignment. CENTER 

.Position = unPoint 

.Escape = com. sun. star. drawing. EscapeDirection. RIGHT 

end With 

idPtColle = lesPtColle.insert(unPtColle) 

print "Identite du nouveau point : " & idPtColle 
ListerPointsdeColleC'cerclel") 
\ End Sub 

Nous declarons une variable ayant la structure Gl uePoi nt2. Une fois cet objet initialise, 
nous le mettons en argument de la methode insert de l'objet collection de points de 
colle. Cette methode nous renvoie l'identite quelle a choisie pour ce point de colle. 

Supprimer un point de colle 

II n'existe pas de fonction hasByldentifier qui permettrait de savoir si un identifica- 
teur est present dans la forme. La methode removeByldentifier de l'objet collection 
de points de colle supprime le point fourni en argument. S'il n'existe pas de point ayant 
cette identite, une exception est declenchee. Nous allons utiliser cette particularite dans 
la macro exemple, en interceptant l'exception avec l'instruction on error Goto. 

rem Codel0-05 .odg bibli : Collages Module3 
Option Explicit 

Sub SupprimerPtColleO 

Dim monDocument As Object, maPage As Object, maForme As Object 
Dim lesPtColle As Object, idPtColle As Long 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi nl") 
maForme = Fi ndObjectByName(maPage , "cerclel") 
lesPtColle = maForme. GluePoints 
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idPtColle = InputBox("Identi te du point a supprimer") 
on error Goto pointNex' intercepter les exceptions 
1 esPtCol 1 e . removeByldent i f i er (i dPtCol 1 e) 

on error Goto 0 

Li sterPoi ntsdeCol 1 e("cercl el") 

exit sub 

pointNex:' removeByldenti fi er a declenche une exception 
on error Goto 0 

MsgBox("Poi nt de colle inexistant ou interdit", 16) 
End Sub 

Vous pourrez verifier qu'il est interdit de supprimer un des points de colle predefinis. 

Relier deux formes par un connecteur 

Nous allons utiliser les notions de point de colle et les caracteristiques de connecteur 
dans la macro suivante. Dans le document du Zip telechargeable, nous avons dessine 
et nomme deux formes que nous allons relier par un connecteur. Comme le connec- 
teur sera positionne par les points de colle des deux formes, il est inutile de le posi- 
tionner a sa creation. 

rem CodelO-05 . odg bibli : Collages Module4 
Option Explicit 

Sub Connecter2Formes() 

Dim monDocument As Object, maPage As Object 
Dim leConnecteur As Object, uneForme As Object 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi nl") 

leConnecteur = monDocument . createlnstance( 

"com . sun . star . drawi ng . ConnectorShape") 

' inutile de definir la position et les dimensions 
' car elles seront imposees par le collage 
maPage. add(leConnecteur) ' ajouter avant de completer 
With leConnecteur 

.EdgeKind = com . sun . star . drawi ng . ConnectorType . LINES 

.StartShape = FindObjectByName(maPage, "carrel") 

.StartGluePointlndex = 1 ' le point a droite 

. EndShape = FindObjectByName(maPage, "cerclel") 

. EndGl uePointlndex = 0 ' le point en haut 
end With 
End Sub 

Pour voir les variantes possibles, changez la valeur de type de connecteur et les 
valeurs d'index. 
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Manipuler plusieurs formes 



L'ordre Z 



Une forme peut en cacher une autre, tout depend de l'ordre dans lequel elles sont affi- 
chees. Cet ordre est defini par la propriete ZOrder, de type Long, que possede chaque 
forme. Une forme peut cacher toutes celles qui possedent un ZOrder inferieur au sien. 

En lisant puis modifiant le ZOrder de vos formes, vous decidez de l'ordre effectif 
d'affichage, independamment de l'ordre dans lequel elles ont ete inserees. 



Pour grouper des formes qui se trouvent sur une meme page, on les met « dans le 
meme sac », c'est-a-dire dans une collection de formes. Les formes sont ajoutees une a 
une dans la collection avec sa methode add, puis la collection est donnee en argument a 
la methode group de l'objet page. Elle renvoie un objet groupe. Le degroupage utilise 
la methode ungroup de la page. Elle prend comme argument l'objet groupe. 

Notre exemple utilise des formes pre-existantes et nominees, pour alleger le code. 
Cette macro va grouper trois formes. Verifiez le groupage apres execution. 

rem CodelO-04 . odg bibli : Selections Module3 
Option Explicit 

Sub GrouperFormesO 

Dim monDocument As Object, maPage As Object, uneForme As Object 
Dim groupage As Object, monCroupe As Object 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi ns") 

groupage = createUnoService(_ 

"com . sun . star .drawn ng . ShapeCol 1 ect i on") 

uneForme = FindObjectByName(maPage, "carreVide") 
groupage . Add(uneForme) 

uneForme = FindObjectByName(maPage, "camembert_entame") 
groupage . Add(uneForme) 

uneForme = FindObjectByName(maPage, "unTriangle") 

groupage . Add(uneForme) 

monCroupe = maPage. group(groupage) 

End Sub 



Grouper des formes 



II est possible de deplacer ou redimensionner un groupe de formes, mais il n'est pas 
possible de modifier par macro les autres caracteristiques : trait, couleur, texte. Effec- 
tuez done ces formatages avant de grouper les formes. 
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Un groupe de formes est assimile a un type special de forme, CroupShape. On le 
recupere comme une forme ordinaire de la page, et on le reconnait par son type. Les 
formes contenues dans le groupe (et qui ne sont plus accessibles directement depuis 
la page) sont recuperees par la methode getBylndex du groupe. Le nombre de 
formes contenues est indique par sa propriete Count. Notez qu'un groupe peut corn- 
porter des formes et des groupes, et ainsi de suite... La macro suivante traite un cas 
simple, pour retrouver notre groupe afin de le degrouper. 

rem CodelO-04 . odg bibli : Selections Module3 
Option Explicit 

Sub rechercherCroupes() 

Dim monDocument As Object, maPage As Object, uneForme As Object 
Dim monCroupe As Object, n As Long, x As Long, info As String 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi ns") 

for n = 0 to maPage. Count -1 ' balayer les formes de la page 
monCroupe = maPage(n) 

if monCroupe . ShapeType = "com. sun. star. drawing. CroupShape" then 
info = "Un groupe existe, il contient : " & chr(13) 
for x = 0 to monCroupe. Count -1 ' balayer les formes du groupe 

uneForme = monCroupe(x) 

info = info & uneForme. Name & chr(13) 
next 

info = info & chr(13) & "Degrouper ?" 

if MsgBox(info, 4) = 6 then maPage. ungroup(monCroupe) 
end if 
next 
End Sub 



Combiner plusieurs formes 

La combinaison de formes se realise de maniere quasi-identique a un groupement. 
On utilisera la fonction combi ne pour combiner, et la methode spl i t pour supprimer 
la combinaison. Comme avec l'interface utilisateur, combinaison et annulation de 
combinaison ne permettent pas de retrouver les objets originels. 

rem CodelO-04 . odg bibli : Selections Module4 
Option Explicit 

Sub Combi nerFormes() 

Dim monDocument As Object, maPage As Object, uneForme As Object 
Dim groupage As Object, maCombi nai son As Object 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Dessi ns") 
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groupage = createUnoService(_ 

"com . sun . star .drawn ng . ShapeCol 1 ecti on") 
uneForme = FindObjectByName(maPage, "carreVide") 
groupage . Add(uneForme) 

uneForme = FindObjectByName(maPage, "camembert_entame") 
groupage . Add(uneForme) 

uneForme = FindObjectByName(maPage, "unTri angl e") 
groupage . Add(uneForme) 

maCombi nai son = maPage. combine (groupage) 

End Sub 

Le resultat de la combinaison est une forme du type CI osedBezi e rShape. Pour annuler 
la combinaison, nous vous demanderons de la selectionner avant de lancer la macro. 

rem Codel0-04.odg bibli : Selections Module4 

Option Explicit 

Sub AnnulerCombinaisonO 

Dim monDocument As Object, maPage As Object, maCombi nai son As Object 
I monDocument = Thi sComponent 
maPage = monDocument. CurrentController.CurrentPage 
maCombi nai son = monDocument. CurrentSelection(O) 
if IsNul 1 (maCombi nai son) then 

MsgBox("Selectionnez la forme combinee", 16) 
el se 

maPage . spl i t (maCombi nai son) 

end if 
End Sub 



Connecter plusieurs formes 

La connexion de formes se realise comme une combinaison de formes. A la place de 
combi ne et spl i t, on utilisera la fonction bi nd pour connecter, et la methode unbi nd 
pour supprimer la connexion. 



Les images 

La premiere partie, insertion, recuperation, suppression d'images, est specifique a 
Draw. Les sections suivantes sont aussi applicables aux images dans Writer et Calc. 

Inserer une image 

Linsertion (du lien) d'une image dans Draw offre des similarites avec l'insertion 
d'une forme. 
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Rem CodelO-10 . odg bibli : leslmages Modulel 
Option Explicit 

Sub AjouterlmageO 

Dim monDocument As Object, maPage As Object, monlmage As Object 
Dim positionlmage As New com. sun. star. awt. Point 
monDocument = ThisComponent 

maPage = monDocument. DrawPages.getByName("Photosl") 

positionlmage. x = 6500 ' 65 mm a droite du coin de la page 
positionlmage. y = 5300 ' 53 mm en dessous du coin de la page 
monlmage = monDocument . createInstance("com . sun . star . drawi ng . GraphicObjectShape") 
monlmage. GraphicURL = ConvertToURL("C:\Docs 0pen0ffice\Logo0pen0ffice.png") 
maPage . add (monlmage) 

resizelmageByWidth (monlmage, 11000) ' largeur en 1/100 de mm 
monlmage. Position = positionlmage 
monlmage. Name = "Logol" 
End Sub 

Nous inserons une forme de type GraphicObjectShape. La propriete GraphicURL 
recoit le chemin complet du fichier contenant l'image. L'image est dimensionnee 
apres son insertion, en frxant sa largeur. Pour conserver les proportions de l'image, 
nous utilisons la routine utilitaire resizelmageByWidth, que nous avons extraite de 
l'annexe B de ce livre. Cette routine est recopiee dans la bibliotheque Standard du 
document exemple. Le positionnement de l'image n'offre rien de nouveau. II est pos- 
sible et recommande de nommer une image en utilisant sa propriete Name. 

Inserer plusieurs images 

Pour inserer plusieurs images, il est necessaire d'obtenir a chaque fois un nouvel objet 
image grace a createlnstance, meme pour plusieurs images identiques. 

Rem CodelO-10 . odg bibli : leslmages Module2 
Option Explicit 

Sub Plusieurslmages() 

Dim monDocument As Object, maPage As Object, monlmage As Object 
Dim positionlmage As New com. sun. star. awt. Point 
monDocument = ThisComponent 

maPage = monDocument. DrawPages.getByName("Photosl") 
' premiere image 

positionlmage. x = 6500 ' 65 mm a droite du coin de la page 
positionlmage. y = 5300 ' 53 mm en dessous du coin de la page 

monImage= monDocument . createlnstance ("com . sun . star . drawi ng .Graphi cObjectShape") 
monlmage. GraphicURL = ConvertToURL("C:\Docs OpenOffice\LogoOpenOffice.png") 
maPage . add (monlmage) 
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resizeImageByWidth(monImage, 11000) ' largeur en 1/100 de mm 

monlmage. Position = positionlmage 

monlmage.Name = "Logo2" 

' deuxieme image 

positionlmage.x = 700 

positionlmage.y = 14100 

monImage= monDocument . createInstance("com . sun . star . drawi ng . Graphi cObjectShape") 
monlmage. GraphicURL = ConvertToURL("C:\Docs 0pen0ffice\Logo0pen0ffice.png") 
maPage . add (monlmage) 

resizeImageByWidth(monImage, 5700) ' largeur en 1/100 de mm 
monlmage. Position = positionlmage 
monlmage.Name = "Logo3" 
End Sub 

Retrouver, supprimer une image 

L'image ayant ete nommee, elle peut etre retrouvee sur une page de dessin en utili- 
sant la routine utilitaire de l'annexe B : Fi ndObjectByName. Nous pouvons ensuite la 
modifier. Ici, nous nous contentons de la selectionner de maniere visible en 
employant la methode sel ect du controleur du document. 

Rem CodelO-lO.odg bibli : leslmages Module3 
Option Explicit 

Sub SelectionnerlmageO 

Dim monDocument As Object, maPage As Object, monlmage As Object 
monDocument = Thi sComponent 

maPage = monDocument. DrawPages.getByName("Photosl") 
monlmage = Fi ndObjectByName (maPage, "Logo2") 
if IsNul 1 (monlmage) then 

print "II n'existe aucune image de ce nom" 
el se 

monDocument . Cur rentControl 1 er . Sel ect (monlmage) 
end if 
End Sub 

La methode remove de l'objet page de dessin permet de supprimer une image : 
maPage. remove (monlmage) 



Proprietes des images 

Une image expose a la fois les proprietes des formes et des proprietes specifiques, 
dont les principales sont listees au tableau 10-41. 
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Tableau 10-41 Proprietes specifiques des images 
Signification 



AdjustRed 


Integer 


Correction de la couleur Rouge, valeur en pourcentage positif ou 
negatif. 


AdjustGreen 


Integer 


Correction de la couleur Vert. 


AdjustBl ue 


Integer 


Correction de la couleur Bleu. 


Adiu^l"! unrinanrp 

/\ \-A J UJ LLUMI 1 II CJ. 1 1 L C 


Intege r 


Correction Hp la lnminnsitp valeur en noiirrentane nositif on nenatif 

1 Ct. LIUI 1 LI tZ 1 LI ILIIIMML/JIILT, VQICUI C I 1 UUUI LCI 1 LCI UC UUJl LI 1 L, LI 1 1 L7L4C1 LI 1 ■ 


AH i u <;i~Con1~ ^ 1~ 

nuj U J LV.UI 1 LI UJ L 


Intege r 


Correction riu cnntrastp valpur pn nourrpntanp nositif on npnatif 

VUI 1 CL-LILfl 1 LIU L.LII 1 11 QJ LL7, VCIIL7LII dl IJ V U 1 L.C 1 1 IU Lj C k/L/Jllll L/U IILTLjULII. 


Gamma 


Double 


Valeur du Gamma. 


Graphi cColorMode 


Long 


Correspond au mode graphique sur la barre d'objets graphiques ; 
constante nommee, voir le tableau 10-42. 


Graphi cCrop 


Object 


Recadrage de I'image ; structure, voir le tableau 1 0-43. 


GraphicURL 


Stri ng 


Chemin d'acces au fichier lie, ou reference du fichier incorpore au 
document. 


Graphi c 


Object 


Caracteristiques du graphique, decrites plus loin. 


Graphi cObjectFi 11 Bitmap Object 


Propriete obsolete, utiliser Graphi c. 



Les corrections ou le recadrage ne concernent que l'affichage dans le document ; elles 
ne modifient pas le fichier image. 

La propriete Graphi cColorMode recoit une constante nommee (tableau 10-42) de la 
forme : 

com . sun . star . drawi ng . Col orMode . NORMAL 

Tableau 10-42 Constantes de GraphicColorMode 



NORMAL 


Standard 


GREYS 


Niveaux de gris 


MONO 


Noir/Blanc 


WATERMARK 


Filigrane 



La propriete Graphi cCrop est une structure decrite dans le tableau 10-43. 

Tableau 10-43 Structure GraphicCrop 



Top 


Long 


Recadrage du haut. 


Bottom 


Long 


Recadrage du bas. 


Left 


Long 


Recadrage du cote gauche. 


Right 


Long 


Recadrage du cote droit. 
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II est necessaire d'utiliser une variable intermediate pour modifier un element. 

dim rognure as object 
rognure = monlmage.GraphicCrop 
rognure. Bottom = -2000 
monlmage.GraphicCrop = rognure 

Une valeur positive rogne l'image, la partie visible s'etendant sur la surface offerte par 
les dimensions actuelles. Une valeur negative reduit l'image par rapport a ses dimen- 
sions, laissant une marge. Les valeurs sont exprimees en 1/100 de millimetres. Notez 
que l'interface utilisateur effectue simultanement un redimensionnement (boutons 
de choix Conserver I'echelle ou Conserver la tail le de l'image). 

Lorsqu'une image est incorporee dans le document, la propriete Graphi cURL contient 
une URL particuliere, par exemple : 

vnd . sun . star .Graphi cOb ject : 100000000000016400000152463C5E09 

Le nom du fichier image integre dans le Zip constituant le document est compose du 
nombre, suivi de l'extension du fichier. Le fichier est stocke dans le repertoire 
Pi ctures du Zip. 

La propriete Graphic fournit un objet donnant d'autres caracteristiques de l'image 
(voir le tableau 10-4). D'apres l'API (service Graphi cDescri ptor), ces informations 
ne sont pas toujours disponibles. 



EXIF 

Par suite du bogue Issue 93716, la propriete SizelOOthMM n'est pas remplie si l'image contient des 
donnees EXIF (comme cela est le cas d'un cliche pris avec un appareil numerique). 



Tableau 10-44 Caracteristiques de l'image 



Alpha 


Boolean 


True si l'image a un canal alpha (valeur de transparence dans chaque 
pixel). 


Animated 


Boolean 


True si l'image est animee. 


Transparent 


Boolean 


True si l'image est transparente. 


BitsPerPixel 


Integer 


Nombre de bits pour coder chaque pixel. 


Graphi cType 


Integer 


Constante nommee, trois valeurs possibles : 
Image vide : com. sun . star .graphi c .Graphi cType . EMPTY 
Image bitmap : com . sun . star .graphi c .Graphi cType . PIXEL 
Image vectorielle : 

com . sun . star . g raphi c .Graphi cType . VECTOR 
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Tableau 10-44 Caracteristiques de I'image (suite) 



SizelOOthMM 


Object 


Taille de I'image sur le document, en 1/100 de mm. Structure Size 
(voir le tableau 10-2). 


Si zePi xel 


Object 


Taille de I'image, en pixels. Structure Si ze (voir le tableau 10-2). La rou- 
tine resi zelmageByWi dth de I'annexe B utilise cette propriete. 



Image lice et image incorporee 

Nous attirons votre attention sur le fait que seul un lien vers I'image est insere et non 
I'image elle-meme. Ceci est une limitation actuelle de l'API. Si vous deplacez, 
renommez, supprimez le fichier image reference, le document affichera une case de 
lien brise avec l'URL du fichier. Pour effectivement inserer dans le document des 
images liees, il faut suivre cette procedure manuelle : 

1 Ouvrir le menu Edition>Liens. 

2 Selectionner l'ensemble des liens images. 

3 Cliquer sur le bouton Deconnecter ; confirmer. 

4 Sauvegarder le document. 



B0GUE Suppression du lien 

Quand un lien d'image est supprime, OpenOffice.org insere dans le document le fichier image au 
format PNG. Or, ce format comprime tres peu le fichier en comparaison avec le format JPEG. Le docu- 
ment final peut alors grossir enormement s'il contient des photographies (voir le rapport Issue 1 5508). 



Avant d'aborder les aspects logiciels, quelques notions sur les images sont necessaires. 
Une image bitmap ne possede pas de dimensions physiques par elle-meme. Elle est 
caracterisee par le nombre de points elementaires (pixels) qui la composent. Ces points 
(colores et de forme carree) sont disposes en matrice rectangulaire. On parle d'une lar- 
geur et d'une hauteur en nombre de pixels. Une image est reproduite sur un ecran ou 
une feuille de papier en effectuant une projection, qui affecte une certaine taille phy- 
sique a chaque pixel, ou, ce qui revient au meme, en decidant du nombre de pixels par 
unite de mesure physique. On emploie habituellement le nombre de points par pouce 
ou PPP (un pouce = 25,4 mm), designe en anglais par le signe DPI (Dots Per Inch). 
Une imprimante laser offre une densite typique de 300 ou 600 DPI. Dimensionner 
une image sur un document revient a changer sa resolution DPI. 

Dans le jargon de l'API, le terme anglais Graphic est utilise pour designer une image bitmap ou vecto- 
rielle. Aucun rapport done avec le concept francais de graphique. 
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Integrer une image dans le document 

Niklas Nebel, developpeur chez Sun MicroSystems, a donne un moyen d'integrer 
une image dans un document, au lieu d'inserer un lien. II consiste a inserer une pre- 
miere fois l'image n'importe ou dans le document, puis a inserer l'image une 
deuxieme fois en recopiant la propriete Graphi cObjectFi 11 Bi tmap obtenue lors de la 
premiere insertion, mais sans remplir la propriete Craphi cURL. L'exemple suivant est 
sous Draw, nous vous laissons deduire la methode pour Writer et Calc. 

Rem CodelO-lO.odg bibli : leslmages Module4 
Option Explicit 

Sub IntegrerlmageFormatPNGO 

Dim monDocument As Object, maPage As Object 

Dim monlmage As Object, ImageL As Object 

Dim positionlmage As New com. sun. star. awt. Point 

monDocument = Thi sComponent 

maPage = monDocument. DrawPages.getByName("Photosl") 

ImageL= monDocument . createInstance("com . sun . star . drawi ng .Craphi cObjectShape") 
ImageL. CraphicURL = ConvertToURL("C:\Docs OpenOffice\Dolomites.jpg") 
maPage. add (ImageL) ' cette image est liee 

positionlmage. x = 6500 ' 65 mm a droite du coin de la page 

positionlmage. y = 5300 ' 53 mm en dessous du coin de la page 

monImage= monDocument . createInstance("com . sun . star . drawi ng . Graphi cObjectShape") 

monlmage. Craphi cObjectFi 11 Bitmap= ImageL. Graphi cObject Fill Bitmap 

maPage. add(monlmage) ' cette image est integree dans le document 

maPage . remove(ImageL) ' supprimer l'image inutile 

resizelmageByWidth (monlmage, 11000) ' largeur en 1/100 de mm 

monlmage. Position = positionlmage 

End Sub 

L'image Dolomites.jpg est disponible dans le meme repertoire du Zip telechar- 
geable. Elle fait 63 Ko. Le document initial grossira de 550 Ko, a cause de la conver- 
sion de l'image au format PNG. Linsertion sans lien de nombreuses photographies 
detaillees est done a eviter. 



Les autres objets inseres dans une page de dessin 

Differents types d'objets peuvent etre inseres dans une page de dessin, ils apparais- 
sent comme des formes d'un certain type. Loutil Xray (voir l'annexe A) vous per- 
mettra d'inspecter ces objets et leurs sous-objets. Les exemples realises sous Draw, 
sont aisement transposables sous Calc ou Writer, qui offrent les memes possibilites. 
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Les objets 0LE2 

II s'agit des elements inseres suivants (liste non exhaustive) : 

• diagramme ; 

• formule, aussi appelee equation ; 

• son (insere par le menu Objet>Son), video, plug-in ; 

• document OpenOffice ; 

• cadre flottant (normalement utilise dans un document HTML). 

lis apparaissent sur la page de dessin comme des formes qui supportent le service 
com. sun. star. drawing.0LE2Shape. Le nom contenu dans la propriete ShapeType de 
ces formes depend de l'objet OLE2. Si ce nom est 
com. sun. star. drawing.0LE2Shape, l'objet offre une propriete EmbeddedObject. Elle 
contient un objet complexe, dont nous utiliserons la propriete Component, qui fournit 
l'objet final : diagramme, formule, document OpenOffice, etc. La liste des services 
supportes permet de preciser de quel type d'objet il s'agit. 

Lexemple suivant liste les objets OLE2 d'une page de dessin Draw. 

rem CodelO-06 . odg bibli : Objetslnseres Modulel 
Option Explicit 

Sub Lister0bjets0LE2() 

Dim maPage As Object, maForme As Object 

Dim conteneurOLE2 As Object, objetOLE2 As Object 

Dim n As Long, sv As String, info As String, cr As String 

cr = chr(13) 

maPage = Thi sComponent . DrawPages . getByName("Exempl e") 

for n = 0 to maPage. Count -1 ' enumerer les formes de la page 

maForme = maPage . getBylndex(n) ' on aurait pu indexer di rectement 
i f maForme . support sService( "com . sun . star . drawing .0LE2Shape") then 
info = "Nom de la forme : " & maForme. Name & cr & cr _ 
& "Type de la forme : " & maForme . ShapeType & cr & cr 
if maForme . ShapeType = "com. sun. star. drawing. 0LE2Shape" then 
conteneurOLE2 = maForme . EmbeddedObject 
objetOLE2 = conteneurOLE2 .Component 

info = info & "Services supportes par l'objet 0LE2 :" 
for each sv in objetOLE2 . SupportedServi ceNames 

info = info & cr & sv 
next 
end if 

MsgBox(info, 0, "Forme 0LE2") 
end if 
next 
End Sub 
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Les formules, ou equations 

L'objectif de notre exemple est de modifier la taille d'une equation du document en 
cours, connaissant le nom donne a la forme. 

I rem CodelO-06 . odg bibli : Objetslnseres Module2 
Option Explicit 

Sub ModifierTailleEquationO 

Dim maPage As Object, maForme As Object, objetOLE2 As Object 
Dim nouvelleTaille As Integer 

maPage = Thi sComponent . DrawPages . getByName("Exempl e") 
maForme = Fi ndObjectByName (maPage , "exemple de formule", _ 
"com . sun . star .drawn ng . 0LE2Shape") 

if IsNul 1 (maForme) then 

MsgBox("La formule n'existe pas", 16) 
el se 

if maForme.ShapeType <> "com. sun. star. drawing. 0LE2Shape" then 

MsgBox("La formule n'existe pas", 16) 
el se 

objetOLE2 = maForme . EmbeddedObject .Component 
if objetOLE2 . supportsServi ce( _ 

"com . sun . star . formul a . Formul aProperti es") then 
nouvelleTaille = InputBox("Donner une nouvelle taille :", "", _ 

objetOLE2 . BaseFontHeight) 
objetOLE2 . BaseFontHeight = nouvelleTaille 
objetOLE2 .Modified = True 
else 

MsgBox("La formule n'existe pas", 16) 
end i f 
end if 
end if 
End Sub 

Pour etre sur d'avoir obtenu l'equation, et non une forme autre du meme nom, nous 
effectuons plusieurs verifications successives : 

1 D'abord, en utilisant la routine de l'annexe B Fi ndOb j ectByName en lui demandant de 
retrouver sur la page de dessin une forme du nom recherche, et supportant le service 
0LE2Shape. Cette routine est recopiee dans la bibliotheque Standard du document. 

2 Puis, en verifiant le type de la forme, afin d'utiliser la propriete EmbeddedObject. 

3 Enfin, on verifie que le document incorpore supporte le service 
Formul aProperti es. 

La macro demande alors a l'utilisateur d'indiquer la nouvelle taille de la police des 
equations, en affichant la valeur actuelle, qui se trouve dans la propriete 
BaseFontHeight. L'outil Xray vous permettrait de visualiser les nombreuses autres 
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proprietes d'une equation. La propriete Modified permet d'informer le document 
que la representation de la formule a change et qu'il faut mettre a jour l'affichage. 

II est tout a fait possible de changer la formule contenue dans l'objet equation. Dans 
la macro precedente, il suffirait d'ajouter cette ligne : 

objetOLE2.Formula= "{2+4} over {1+1} = 3" 

Nous intervenons cette fois sur la propriete Formula qui attend un texte tel qu'il 
aurait ete saisi dans l'editeur d'equation. 

Ces exemples ne sont evidemment pas exhaustifs. L'API couvrant les equations se 
situe dansle module com. sun. star. formula etle service FormulaProperties. 

Les objets video et son 

II s'agit des objets inseres par le menu lnsertion>Video et son. On obtient une forme 
supportant les services com. sun. star. drawing.MediaShape et com. sun. star, 
drawi ng . Shape. La propriete ShapeType de la forme a pour valeur com. sun. star, 
drawi ng . Shape. La forme expose aussi les proprietes Medi aURL et Loop. 



Les styles 

Nous avons indique au chapitre 7 les elements communs a la gestion des styles. Nous 
abordons maintenant les particularites des documents Draw et Impress. 

En affichant le panneau Styles et formatage vous constatez que toutes les proprietes de 
formes sont reglables sur un style d'images. Effectivement, vous retrouvez les pro- 
prietes que nous avons decrites ainsi que d'autres. II suffit de les modifier sur votre 
objet style pour le changer. 



BOGUE Objets styles de Draw 

Si vous cherchez a explorer le contenu d'un style de Draw, soit dans TIDE en mettant en temoin une 
variable contenant un style, soit avec I'outil Xray, I'application OpenOffice.org va planter. Ceci est du a 
une structure incorrecte de l'objet style. Ce probleme est signale par Tissue 97880. 



Pour creer un nouveau style d'images, on invoque le service Styl e : 
uneFamille = lesFamilles.getByName("graphics") 

nouvStyl e = monDocument . CreateInstance("com . sun . star . styl e . Styl e") 
uneFamille. insertByName("Objet ombre a gauche", nouvStyle) 
nouvStyl e.ParentStyle = "Objet avec ombre" ' heriter d'un style 
nouvStyle.ShadowXDi stance = -300 
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Imprimer 

Le mecanisme general d'impression est decrit au chapitre 7. Nous traiterons ici des 
particularites de Draw. 

Chaque forme dispose d'une propriete Printable, de type Boolean. La valeur True 
autorise son impression. De meme, chaque couche expose une propriete 
IsPri ntabl e qui permet d'imprimer ou non les objets qui lui sont associes. 

Configuration d'impression 

Les proprietes listees au tableau 10-45 correspondent aux cases a cocher de l'interface 
utilisateur lmpression>Options. II s'agit des proprietes de configuration du document, qui 
sont obtenues en invoquant le service DocumentSetti ngs, comme dans cet exemple. 

rem Code07-03 .odg bibli : Imprimer Module4 
Option Explicit 

Sub ConfiglmpressionO 

Dim monDocument As Object, conf As Object, servConfig As String 
monDocument = Thi sComponent 

servConfig = "com. sun. star. drawing. DocumentSetti ngs" 

conf = monDocument. createlnstance(servConfig) 
print conf . PrinterName 
End Sub 



Tableau 10-45 Proprietes d'impression pour Draw 



Propriete Type Signification 


IsPri ntFi tPage 


Boolean 


True pour adapter la page a I'espace imprimable. 


IsPri ntTi 1 ePage 


Bool ean 


True pour imprimer en mosai'que. 


Pri nterName 


String 


Norn de I'imprimante utilisee par le document. 


IsPri ntPageName 


Boolean 


True pour imprimer le nom de la page. 


IsPri ntDate 


Boolean 


True pour imprimer la date. 


IsPri ntTi me 


Bool ean 


True pour imprimer I'heure. 


IsPrintBooklet 


Boolean 


True pour imprimer en format prospectus. 


IsPri ntBookletBack 


Bool ean 


True pour n'imprimer que le verso du prospectus. 


IsPri ntBookl etFront 


Boolean 


True pour n'imprimer que le recto du prospectus. 


PrintQuality 


Long 


Qualite d'impression 
0 : Normal 

1 : Niveaux de gris 

2 : Noir et Blanc seulement 
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Configuration du document 



Les proprieties listees au tableau 10-46 concernent la mise a l'echelle du document et 
l'unite de mesure employee (pour les cotations). Avec 1'interface utilisateur, ceci est 
defini dans le menu Outils>Options>Dessin>General. Par programmation, on y accede 
en invoquant le service DocumentSetti ngs pour le document en cours. 

Tableau 10-46 Proprietes de document Draw 



Propriete 


Type 


Signification 




MeasureUnit 


Integer 


Unite de mesure par defaut, constante nommee. 


Seal eNumerator 


Long 


Numerateur de l'echelle du document. 


Seal eDenomi nator 


Long 


Denominates de l'echelle du document. 



Les principales unites de mesure sont listees au tableau 10-47. Les constantes nom- 
inees sont de la forme : 

| com. sun. star, util . Measurellni t . MM 

Tableau 10-47 Constantes d'unite de mesure 



MM_100TH 


1/1 00 de mm. 


MM 


mm 


CM 


cm 


M 


m 


KM 


km 


TWIP 


Twip 



INCH 


pouce 


FOOT 


pied 


MILE 


mile 


PICA 


pica 


POINT 


point 


PERCENT 


pourcentage 



L'echelle ne donne des resultats coherents que pour un rapport numerateur/denomi- 
nateur inferieur ou egal a 1. Dans l'exemple suivant nous avons place des cotations 
sur la page de dessin. La macro va changer l'echelle de cotation pour le document. 
Observez le changement des valeurs affichees sur le dessin. 



rem Codel0-09 . odg 
Option Explicit 



bibli : Config Modulel 



Sub ConfigEchelleO 

Dim monDocument As Object, conf As Object, servConfig As String 
monDocument = Thi sComponent 

servConfig = "com. sun. star. drawing. DocumentSetti ngs" 
conf = monDocument. createlnstance(servConfig) 
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' alterner entre deux echelles tres differentes ! 

"if conf .Measurellnit = com. sun. star. util .MeasureUnit.MM then 

conf .MeasureUnit = com . sun . star . uti 1 .MeasureUni t . KM 

conf .Seal eNumerator = 3 

conf .Seal eDenomi nator = 100000 
el se 

conf . MeasureUni t = com. sun. star. util .MeasureUnit.MM 

conf .Seal eNumerator = 7 

conf .Seal eDenomi nator = 10 
end if 
End Sub 



Specificites d'lmpress par rapport a Draw 

Nous decrivons ici les quelques particularites d'lmpress. 

Couches de dessin 

Depuis la version 2.0 d'OpenOffice.org, les couches de dessin ne sont plus disponi- 
bles dans Impress. 

La configuration d'execution des diaporamas 

La pseudo-propriete Presentation d'un document Impress nous donne un objet 
comportant des proprietes gouvernant le fonctionnement des diaporamas du docu- 
ment. La liste en est donnee au tableau 10-48. Ces proprietes peuvent etre lues ou 
modifiees, elles sont sauvegardees avec le document. 

Dim monDocument As Object, pr As Object 
monDocument = Thi sComponent 
pr = monDocument . Presentation 

MsgBox(pr.CustomShow) ' nom du diaporama personnalise utilise 

Tableau 10-48 Proprietes du diaporama 



All owAni mati ons 


Bool ean 


True pour autoriser les animations GIF. 


CustomShow 


Stri ng 


Nom du diaporama personnalise utilise (ou chame vide). 


Fi rstPage 


Stri ng 


Nom de la page debutant le diaporama (ou chame vide). 


IsAlwaysOnTop 


Boolean 


True impose le diaporama au premier-plan. 
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Tableau 10-48 Proprietes du diaporama (suite) 



IsAutomati c 


Bool ean 


Fal se change les diapos automatiquement ! Cet indicateur 
correspond a Transition de diapo manuelle dans les 
parametres du diaporama. 


IsEndl ess 


Bool ean 


True repete le diaporama inlassablement. 


IsFullScreen 


Boolean 


True affiche le diaporama en plein ecran. 


IsMouseVisible 


Boolean 


True affiche le curseur de souris. 


Pause 


Long 


Duree de la pause, en secondes, avant la relance du diapo- 
rama. 


StartWi thNavi gator 


Bool ean 


True affiche le navigateur. 


UsePen 


Boolean 


True affiche le pointeur crayon. 



Rappel Diaporama personnalise 

Un diaporama personnalise permet de choisir I'ordre d'affichage des diapos, d'afficher plusieurs fois la 
meme diapositive au cours du diaporama, et de ne pas toutes les afficher. L'utilisateur peut definir plu- 
sieurs diaporamas personnalises. 



Lancer un diaporama 

Le meme objet obtenu par la pseudo-propriete Presentation du document Impress 
expose plusieurs methodes servant a l'execution d'un diaporama (voir le 
tableau 10-49). 

Tableau 10-49 Methodes du diaporama 



i sRunni ng 


Renvoie True si le diaporama est en cours d'affichage. 


00o3.0 


start 


Demarre le diaporama avec ses parametres. 


OOo 1.1 


startWi thArguments 


Demarre le diaporama avec des parametres imposes. 


OOo 3.0 


rehearseTi mi ngs 


Demarre le diaporama en presentation chronometree. 


OOo 1.1 


end 


Arrete le diaporama. 


OOo 1.1 



Ces methodes s'utilisent sans argument, a l'exception de startWi thArguments qui 
recoit un tableau de PropertyVal ue. Chaque element du tableau indique la valeur a 
utiliser pour une propriete du diaporama, a la place de la valeur enregistree. Ceci 
permet d'imposer certaines valeurs sans modifier la configuration du diaporama. Les 
proprietes utilisables sont celles du tableau 10-48. 
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rem CodelO-ll.odp bibli : Standard Module2 
Option Explicit 

Sub lancerPresentation 
Dim monDocument As Object, pr As Object 
Dim props(l) As New com . sun . star . beans . PropertyVal ue 
monDocument = Thi sComponent 
props (0) . Name = "IsFull Screen" 
props (0) .Val ue = False 
props(l) . Name = "StartWithNavigator" 
props(l) .Value = True 
pr = monDocument . Presentati on 
pr . startWithArguments(propsO) 
||! End Sub 



ASTUCE Tableau de PropertyValue 

La routine utilitaire CreateProperti es de I'annexe B vous simplifiera le codage, si vous souhaitez 
imposer de nombreux parametres. 



Intervenir pendant un diaporama 

Depuis la version 2.0 d'OpenOffice.org, il nest plus possible par action de l'API de 
modifier directement l'affichage d'une forme dans une diapo pendant 1' execution de 
la presentation. La macro fonctionnera correctement en mode conception, mais ne 
fera aucun changement visible durant la presentation. 

La version 3.0 d'OpenOffice.org introduit l'interface XSlideShowController per- 
mettant d'intervenir sur le deroulement du diaporama en cours. On obtient cette 
interface a partir de la pseudo-propriete Controller de l'objet obtenu par 
Presentation : 

rem CodelO-ll.odp bibli : Standard Modulel 
Option Explicit 

Sub Uti 1 i serCont rol eurDeDi aporamaO 
Dim pc As Object 

pc = Thi sComponent. Presentation. Controller 

if IsNull(pc) then Exit Sub ' le diaporama n'est pas en cours 
' exemple d ' uti 1 i sati on 

pc.gotoSlideIndex(4) ' afficher la diapo de rang 4 dans le diaporama 
End Sub 

Avant d'utiliser l'interface, nous verifions que l'objet obtenu existe bien, car il n'est 
disponible que si un diaporama est en cours. Cette interface comporte de nom- 
breuses methodes, listees dans le tableau 10-50. 
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Tableau 10-50 Methodes de controle du diaporama 
lesultat 



i sRunni ng 


aucun 


Bool ean 


True si le diaporama est en cours d'affichage. 


isEndless 


aucun 


Boolean 


True si le diaporama se repete inlassablement. 


"i sFul 1 Screen 


aucun 


Bool ean 


True si le diaporama s'affiche en plein ecran. 


i sActi ve 


aucun 


Bool ean 


True si les actions souris sont prises en compte. 


activate 


aucun 


aucun 


Prendre en compte les actions de souris. 


deactivate 


aucun 


aucun 


Ignorer les actions de souris. 


i sPaused 


aucun 


Bool ean 


True si le diaporama est en pause. 


pause 


aucun 


aucun 


Inhiber les transitions automatiques. Le diaporama continue 
soit apres appel a resume, soit en actionnant une touche 
une fois la macro terminee. 


resume 


aucun 


aucun 


Reprendre le cours du diaporama. 


blankScreen 


Long 


aucun 


Afficher un ecran vide, dont la couleur est donnee en argu- 
ment. Le diaporama continue soit apres appel a resume, 
soit par un die de souris ou une action sur le clavier, une fois 
la macro terminee. 


getSl ideCount 


aucun 


Long 


Nombre de diapos affichees sur I'ensemble du diaporama. 
Un diaporama personnalise peut afficher plusieurs fois la 
meme diapo. 


getCurrentSl i delndex 


aucun 


Long 


Rang, debutant a zero, de la diapo dans le diaporama. 


getNextSl i delndex 


aucun 


Long 


Rang de la prochaine diapo dans le diaporama. 


get SI i de By Index 


Long 


Object 


Renvoie I'objet page de la diapo de rang donne en 
argument. 


gotoSli delndex 


Long 


aucun 


Afficher le diaporama a la diapo de rang donne en 
argument. 


getCurrentSl i de 


aucun 


Object 


Renvoie I'objet page de la diapo actuelle. 


gotoFi rstSl i de 


aucun 


aucun 


Afficher la premiere diapo du diaporama. 


gotoLastSlide 


aucun 


aucun 


Afficher la derniere diapo du diaporama. 


gotoNextSl i de 


aucun 


aucun 


Afficher la diapo suivante du diaporama. 


gotoPrevi ousSl i de 


aucun 


aucun 


Afficher la diapo precedente du diaporama. 


gotoSlide 


Object 


aucun 


Afficher la diapo dont I'objet page est donne en argument. 
Cette diapo peut ne pas exister dans le diaporama en cours. 


gotoBookmark 


Stri ng 


aucun 


Afficher la diapo dont le nom est donne en argument. 
Cette diapo peut ne pas exister dans le diaporama en cours. 


gotoNextEffect 


aucun 


aucun 


Afficher le prochain effet d'animation, ou la prochaine 
diapo. 



Manipuler les documents OpenOffice.org 

Troisieme partie 



Tableau 10-50 Methodes de controle du diaporama (suite) 



stopSound 


aucun 


aucun 


Arreter les sons en cours (mais ne semble pas fonctionner a 
ce jour). 


addSl i deShowLi stener 


Object 


aucun 


Ajouter un Listener. 


removeSl i deShowLi stener 


Object 


aucun 


Supprimer un Listener. 



L'interface XSlideShowController comporte aussi des attributs, listes au 
tableau 10-51. On les utilise comme des proprietes. Ces attributs ne fonctionnaient 
pas correctement lors de nos essais en pre-version 3.1. 

Tableau 10-51 Attributs de controle de diaporama 





AlwaysOnTop 


Bool ean 


True impose le diaporama toujours au premier-plan. Ne fonctionne pas. 


MouseVi si bl e 


Bool ean 


True affiche le curseur de souris dans le diaporama. Ne fonctionne pas. 


UsePen 


Bool ean 


True affiche le crayon. N'est pas pris en compte sur la diapo courante. 


PenCol or 


Long 


Couleur du trace de crayon. N'est pas pris en compte sur la diapo courante. 



La page de notes 



Chaque page de dessin d'un document Impress est associee a une page de notes, 
qu'on peut obtenir avec la propriete Notes Page de la page. 

Cette page de notes a toutes les proprietes d'une page de dessin : tout ce qui a ete dit 
a ce propos lui est done applicable. Par defaut, on trouve dans la page de notes deux 
formes, chacune d'un type special : 

I com . sun . star . presentati on . PageShape 
com. sun . star . presentation . NotesShape 

La premiere contient une reproduction de la diapo, la deuxieme contient les notes 
proprement dites. 



NotesPage 

Une page de notes a elle aussi une propriete Notes Page ! El le n'est d'aucune utilite, car elle ne donne 
acces qu'a elle-meme. 



Nous allons enumerer les objets qui se trouvent sur la page de notes de la page 
Di apol, et afficher le texte de la note. Cette macro est tres similaire a remuneration 
des formes dans une page de dessin, vue plus haut. 
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rem CodelO-07 . odp bibli : Libraryl Modulel 
Option Explicit 

Sub formesDeNotes() 

Dim monDocument As Object, maPage As Object, maNote As Object 
Dim maForme As Object, typF As String, n As Long 
monDocument = Thi sComponent 

maPage = monDocument . DrawPages . getByName("Di apol") 

maNote = maPage. NotesPage 

for n = 0 to maNote. Count -1 
maForme = maNote(n) 
typF = maForme . ShapeType 
print "Type de la forme = " & typF 

if typF = "com. sun. star. presentation. NotesShape" then 
MsgBox(maForme. Text. String) ' texte de la note 

end if 
next 
End Sub 

Chaque arriere-plan est aussi associe a sa page de notes, elle aussi accedee par la pro- 
priete NotesPage de l'objet arriere-plan. 

La page prospectus 

Le mode d'affichage Page de prospectus (en anglais, handout) reproduit plusieurs 
diapos sur une meme page, pour fournir un resume imprime de la presentation. 

L'objet page de prospectus est accessible par la propriete HandoutMasterPage de 
l'objet document. II y a peu a dire de cette page ; on ne peut modifier avec l'API le 
nombre de diapos quelle contient, seulement le connaitre avec la propriete Count. 

Les styles Impress 

La famille de styles Standard correspond aux styles de presentation. Dans cette 
famille, les methodes hasByName et getByName ne reconnaissent que le nom interne 
anglais de ces styles. Void la correspondance nom interne/nom localise : 

• title : Titre 

• subtitle : Sous-titre 

• background : Arriere-plan 

• backgroundobjects : Objets d'arriere-plan 

• notes : Notes 

• outl i nel a out! i ne9 : Plan 1 a Plan 9 
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Nous ne pouvons pas creer de nouveaux styles dans la famille Standard, ni supprimer 
un style existant, seulement le modifier. 

Configuration de document 

Les proprietes d'unite de mesure et d'echelle ne sont pas disponibles. 

Configuration d'impression 

Pour obtenir la configuration d'impression d'un document Impress, on emploiera le 
service : 

servConfig = "com. sun. star. presentation. DocumentSettings" 

On obtient les proprietes d'impressions decrites pour Draw, et quelques autres listees 
au tableau 10-52, specifiques a Impress. 



Tableau 10-52 Proprietes d'impression specifiques a Impress 



Propriete Type 


Signification 


IsPri ntDrawi ng 


Boolean 


True pour imprimer les diapos. 


IsPn'ntNotes 


Boolean 


True pour imprimer les notes de page. 


IsPrintHandout 


Boolean 


True pour imprimer les diapos a plusieurs par page 
(resume de presentation). 


IsPri ntOutl i ne 


Bool ean 


True pour imprimer le plan. 


Is PrintHidden Pages 


Bool ean 


True pour imprimer les diapos cachees. 



Conclusion 

De nombreux objets et methodes a vocation graphique, tels que les primitives de bases 
mais aussi les points de colle ou les groupements sont disponibles pour realiser des des- 
sins (ou formes) dans Draw. La plupart des principes decrits ici sont aussi valables pour 
les documents Writer ou Calc. Quant a Impress, c'est essentiellement un document 
Draw enrichi de fonctionnalites supplementaires que nous avons detaillees. 

Ce chapitre clot la presentation de l'API propre aux composants Writer, Calc, Draw 
et Impress. La quatrieme partie de ce livre va elargir le recours a l'API au contexte du 
developpement d'applications. 
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Construire des 
applications avec 
OpenOffice.org 

Savoir modifier les documents OpenOffice.org ne suffit generalement pas pour 
obtenir une application utilisable. Dans cette partie, vous apprendrez a afficher des 
dialogues tout a fait semblables a ceux des applications classiques. Vous pourrez 
interroger ou modifier une base de donnees, effectuer un publipostage, et concevoir 
des formulaires utilisant des macros. Nous exposerons enfin d'autres fonctionnalites 
de l'API ainsi que des methodes sophistiquees qui vous aideront a realiser des pro- 
grammes plus puis 



11 

Les boites de dialogue 



Nous avons vu au chapitre 5 comment afficher des informations et obtenir une 
reponse de l'utilisateur. L'instruction Msg Box est parfaite pour afficher un court texte 
d'information ou une question fermee qui attend une reponse telle que Oui, Non ou 
Annuler. Quant a l'instruction InputBox, elle est d'un aspect peu esthetique, 
n'effectue aucun controle des donnees saisies et ne vous permet de demander qu'une 
information a la fois. 

Grace aux boites de dialogue, vous pourrez presenter de maniere conviviale les diffe- 
rentes options de votre programme, recevoir plusieurs informations en un seul pan- 
neau, afficher des textes entiers. Vous avez le choix entre plusieurs langages de pro- 
grammation pour realiser vos boites de dialogue, mais OOoBasic permet de les gerer 
de facon simple. 



API Reference sur les boites de dialogue (en anglais) 

Le Developer's Guide decrit les boites de dialogue dans deux chapitres redondants, OpenOffice.org Basic 
and Dialogs et Graphical User Interfaces. Le premier de ces chapitres est oriente programmation Basic, le 
second est une description adaptee a d'autres langages de programmation, avec des exemples en Java. 
► http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ 
OpenOffice.org_Developers_Guide 
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Construire une bofte de dialogue avec PEDI 

L'onglet de dialogue 

Ouvrez un nouveau document, puis dans ce document, creez une nouvelle biblio- 
theque Basic que vous nommerez Premier-Dialogue. Dans l'EDI, cliquez avec le 
bouton droit sur la zone des onglets de modules et choisissez lnserer>Bo?te de dialogue 
Basic. Vous obtenez la boite de dialogue vierge de la figure 11-1. 

A savoir 

Les exemples sont realises sur des documents Writer, mais ils sont tout aussi valides sous d'autres types 
de document OpenOffice : Calc, Draw... 




L'onglet Dialogl peut etre renomme comme pour un onglet de module. La fenetre 
vierge au centre de la feuille est le panneau de la boite de dialogue. Avec le menu Aff i- 
chage>Barre d'outils nous avons fait apparaitre la Boite a outils, que nous avons ancree 
dans la fenetre Basic. La plupart des icones de la Boite a outils sont des elements de 
dialogue, appeles controles. 

Selectionnez le panneau de dialogue avec la souris : pour cela, cliquez precisement 
sur un des bords du panneau. Des marques de redimensionnement apparaissent et le 
curseur de la souris devient un curseur de deplacement ou un curseur de dimension- 
nement, comme sur la figure 11-1. 
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La fenetre des proprietes 

Tout en gardant selectionne le panneau de dialogue, cliquez avec le bouton droit sur 
un des bords et choisissez Proprietes. Vous obtenez une fenetre fiottante et redimen- 
sionnable, representee sur la figure 11-2. Vous pouvez egalement y acceder depuis la 
Boite a outils, en cliquant sur l'icone reproduite en marge. 



Figure 11-2 

La fenetre des proprietes 




Vous aurez tres souvent a utiliser la fenetre des proprietes. Grace a elle, vous allez 
inspecter et modifier les caracteristiques de l'objet selectionne, dans le cas present 
celles du panneau de dialogue, mais aussi celles de chacun des controles que vous 
allez y deposer. Comme cette fenetre est encombrante, n'hesitez pas a la redimen- 
sionner, la deplacer, la faire disparaitre et reapparaitre. Elle comporte deux onglets, 
General et Evenements. 

L'onglet General 

La plupart des proprietes listees sur cet onglet existent aussi pour les autres controles. 
Les plus interessantes pour le panneau dialogue sont : 

• Nom - Le nom du dialogue, qui peut etre different du nom du module de 
dialogue ; inscrivez DialogueUn. 

• Titre - Le texte qui apparait dans la barre de titre du dialogue ; inscrivez ici Mon 
premier dialogue. 
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• Hauteur, Largeur - Les dimensions du panneau de dialogue. 

• PositionX, PositionY - La position du coin du haut et a gauche du panneau de 
dialogue. 



Dimensions et positions dans les dialogues 

L'unite de mesure n'est pas le pixel, ni meme le twip, mais le Map AppFont, qui est lie aux hauteur et lar- 
geur moyennes des caracteres de la police systeme. L'avantage est d'obtenir un panneau proportionne 
aux textes affiches par le systeme. 



L'onglet Evenements 

En cliquant sur l'onglet Evenements de la fenetre des proprietes, vous verrez appa- 
raitre une liste (figure 11-3) : 



Figure 11-3 

L'onglet Evenements du 
panneau des proprietes 



Proprietes : Dialog 



General Evenements | 

Reception de focus 

Perte de focus 



f 



Touche enfoncee 

Apres avoir lache latouche.. 

Souris aTinterieur 

Deplacement de la souris et touche 

Deplacement de la souris | 

Bouton de souris enfonce.. 
Bouton de souris relache... 
Souris a I'exterieur 




Cet onglet affiche la liste des differents evenements concernant le panneau de dia- 
logue. Vous obtiendrez une liste similaire pour chacun des controles que vous depo- 
serez sur la boite de dialogue. 

L'onglet Evenements sert a lancer une macro lorsqu'un evenement particulier survient. 
Cette macro effectuera un petit traitement, par exemple memoriser une information 
dans une variable pour un traitement ulterieur. La boite de dialogue reste affichee, et 
selon les actions de l'utilisateur plusieurs evenements seront peut-etre declenches 
successivement, jusqu'a la fermeture de la boite de dialogue. 

Pour affecter une macro a un evenement, cliquez sur la case a la droite de 
I'evenement : le panneau de selection s' affiche (figure 11-4). 

1 Cliquez sur le bouton Macro... Apres quelques secondes (chargement du JRE), un 
nouveau panneau s' affiche (figure 11-5) pour selectionner la macro a executer. 
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Figure 11-5 

Lier un evenement a une macro 




Vous pouvez selectionner une macro (ou script) ecrite dans un des langages de 
script supportes par OpenOffice.org : Basic, JavaScript, Java compile, BeanShell, 
Python. Depuis un document, on peut choisir un script situe dans Mes macros ou 
dans Macros OpenOffice.org ou encore dans le document lui-meme (ici appele 
« Sans » car pas encore sauvegarde). 
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2 Deroulez l'arbre des documents. 

3 Deroulez l'arbre des modules Basic du document. 

4 Choisissez un module. 

5 Choisissez une macro dans le module. 

6 Cliquez sur le bouton OK. Le panneau se ferme, et le panneau precedent est mis a 
jour, comme sur la figure 11-6. 



Figure 11-6 

Lier un evenement a une macro 




Nous pouvons ainsi savoir quels evenements ont un traitement particulier et even- 
tuellement en supprimer avec le bouton Supprimer. Le bouton Composant permet de 
lancer une des methodes d'un composant UNO. Certains langages permettent de 
creer de tels composants, tels Java, C++, Python. Cliquez le bouton OK pour valider 
les modifications effectuees. 

Si plus tard vous changez le nom de votre macro, pensez a reaffecter la macro a l'eve- 
nement quelle doit traiter. Notez que la macro est toujours appelee sans argument, 
bien qu'un objet Event puisse etre recu en argument dans la declaration de la macro, 
comme nous le verrons plus loin dans ce chapitre. 



Attention Les evenements repetitifs 

Certains evenements sont declenches jusqu'a plusieurs fois par seconde, comme le deplacement de sou- 
ris. Ce genre d'evenement doit etre traite seulement quand c'est absolument necessaire, et avec des 
macros tres courtes. Dans la plupart des cas, vous traiterez des evenements plus simples, comme le 
declenchement d'un bouton. 
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Votre premiere bofte de dialogue 

Une boite de dialogue se construit en deposant des controles un a un sur le panneau 
de dialogue. Nous commencerons par les controles les plus simples, qui ont aussi 
l'interet de presenter des proprietes que vous retrouverez dans la plupart des autres 
controles. 



[.'etiquette 

bbc Le controle Etiquette (Label) sert a afficher une information non modifiable par 
I'utiiisateur. Dans l'EDI, cliquez sur l'icone ABC dans la liste des controles, puis 
mettez la souris au-dessus du panneau de dialogue et cliquez-glissez pour obtenir un 
rectangle blanc allonge horizontalement. II contiendra le texte Label 1. 

Faites apparaitre la fenetre des proprietes, en gardant la selection du rectangle. Dans 
le champ de la propriete Etiquette, tapez le texte : « Voulez-vous lancer cette 
macro ? ». Appuyez sur la touche Entree ou cliquez sur le champ d'une autre pro- 
priete et vous devriez obtenir quelque chose de voisin de la figure 11-7. 



Figure 11-7 

Insertion d'un controle 
Etiquette 




Vous avez certainement remarque que le texte n'apparait pas en totalite dans le 
champ Titre ; ce n'est pas grave, il suffit d'augmenter la largeur de la fenetre des pro- 
prietes, ou de cliquer sur le triangle a droite du champ. 

Cependant, le texte affiche dans le controle est tronque, lui aussi ! Avec la souris, il 
suffit d'augmenter la largeur du rectangle. Toujours avec la souris, exercez-vous a 
redimensionner et a deplacer ce controle, auquel Basic a donne le nom Label 1, mais 
que vous pouvez renommer a votre convenance. 

Le controle Label sert uniquement a afficher un texte fixe. Neanmoins, il a plusieurs 
apparences que vous allez decouvrir en jouant avec les proprietes. 

• Alignement - Positionnez le texte dans son rectangle. 

• Bordure - Essayez les differentes possibilites. Seul un cadre « plat » permet de 
changer la couleur de bordure. 
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• Couleur d'arriere-plan - Essayez des couleurs claires. 

• Police - Changez la police, ou sa taille. 

• Coupure de mot - Choisissez Oui, puis redimensionnez le rectangle pour autori- 
ser plusieurs lignes. Vous pouvez forcer un retour a la ligne dans le texte, avec le 
raccourci Maj + Entree. 

En fonction de vos besoins, vous decidez done de 1' aspect le plus approprie de votre 
controle. Ceci ne change absolument rien dans le codage de votre macro. La preuve : 
nous n'avons encore rien programme ! 

Le Bouton 

q Un controle Bouton (Button) sert a declencher un traitement lorsque l'utilisateur 
l'actionne. De la meme maniere que precedemment, choisissez l'icone dans la liste des 
controles et dessinez un rectangle sur le panneau du dialogue. Affichez les proprietes. 

Le bouton obtenu est nomme par Basic : CommandButtonl. Le comportement d'un 
bouton est influence par sa propriete Type de Bouton. II est possible de proposer une 
image (elle doit etre petite, environ 16x16 pixels) a cote du libelle du bouton. Pour 
eviter le bogue Issue 83964, creez le bouton sans modifier son type (qui est Par 
defaut), puis recherchez une image en cliquant le bouton a cote de la propriete Image 
de l'EDI. Reglez ensuite la propriete Alignement des images et enfin modifiez si vous 
le souhaitez le type de bouton. 

Le bouton Standard 

La propriete Type de Bouton est initialement a Par defaut, qui correspond a un 
bouton standard. Un bouton de ce type sert a declencher un evenement, qui doit 
alors etre pris en compte avec une routine specifique. Pour le moment, nous nous 
contenterons des trois types les plus simples et les plus frequents que sont OK, 
Annuler, Aide. 

Le bouton OK 

Avec la propriete Etiquette changez le titre du bouton en Oui. Changez le type de 
Bouton en OK. Vous venez de creer un bouton special : quand l'utilisateur clique sur ce 
bouton, le dialogue se termine avec une valeur de retour specifique. Ce type de 
bouton ne declenche pas de routine d'evenement. 

Dans le champ Texte d'aide des proprietes du bouton Oui, tapez : « Executer le 
dialogue ». Ce texte apparaitra sous forme de bulle au passage de la souris. 
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Le bouton Annuler 

Glissez encore une fois la souris sur le panneau de dialogue pour obtenir un 
deuxieme bouton. Le bouton obtenu est nomme par Basic : CommandButton2. 
Changez le titre du bouton en Non. Changez le type de bouton en Annuler. Vous 
venez de creer un autre bouton special : quand l'utilisateur clique sur ce bouton, le 
dialogue se termine avec une autre valeur de retour specifique. En fait, ce bouton 
effectue exactement la meme action que de cliquer sur la case de fermeture de 
fenetre. Ce type de bouton ne declenche pas de routine d'evenement. 

Le bouton Aide 

II existe un dernier type de bouton, le bouton Aide. Dans son fonctionnement de 
base, il permet d'afficher la page principale de l'aide F1 d'OpenOffice.org et even- 
tuellement de lancer une routine d'evenement. II est possible de creer des extensions 
qui utilisent ce bouton pour afficher une page d'aide propre au panneau de dialogue. 



Exercez-vous a selectionner un des controles de la boite : il suffit de cliquer dessus. 
Deplacez-le en glissant avec la souris. Redimensionnez-le. Pour selectionner plu- 
sieurs controles a la fois essayez deux methodes : 

• un clic sur le premier controle, un Maj + die sur les autres ; 

• dans la barre flottante des controles, choisissez l'icone Selection ; cliquez en dehors 
d'un controle et faites glisser la souris pour creer un rectangle pointille englobant 
les controles a selectionner. 

Quand un groupe de controles est selectionne, vous pouvez le deplacer sans modifier 
leurs positions relatives, ou effectuer un redimensionnement global. 

La fenetre des proprietes affiche les valeurs de proprietes qui sont identiques pour 
tous les objets du groupe. Cela peut servir a modifier globalement la taille des bou- 
tons, par exemple. 

Attention, si vous selectionnez uniquement le panneau de dialogue, son deplacement 
laisse les controles sur place ! Done selectionnez l'ensemble avec la technique du rec- 
tangle pointille, puis deplacez le groupe. 



Apres quelques ajustements, vous obtiendrez un dialogue similaire a celui de la 



Ajuster les elements du dialogue 



Tester le dialogue 



figure 11-8. 
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Figure 11-8 

Votre premiere 
boTte de dialogue 




C'est le moment de tester l'aspect final de votre dialogue. Dans la liste des controles, 
cliquez sur l'icone indiquee par le curseur de souris sur la figure. 

Le panneau de dialogue s'affiche. Deplacez la souris au-dessus du bouton Oui, une 
bulle d'aide apparait. Cliquez sur un des boutons, ou sur la croix de fermeture de 
fenetre et le dialogue disparait. 

L'interet du test est de voir votre dialogue tel qu'il se presentera a l'utilisateur. Et ceci 
sans avoir encore ecrit une seule ligne de codage ! Evidemment, il n'y a aucune exe- 
cution reelle. Aucun evenement nest produit dans ce mode de test de l'interface. 

Utilisez l'EDI pour changer sur le bouton Non la propriete Type de Bouton en Par 
defaut. Testez de nouveau : le panneau de dialogue reste present quand vous cliquez 
sur ce bouton. Un bouton de type Par defaut ne fait rien par lui-meme, il faut affecter 
une macro a l'evenement Lors du declenchement. Cliquez sur l'autre bouton ou sur la 
case de fermeture de fenetre. Dans l'EDI, remettez le type de bouton sur Annuler. 



Executer le dialogue 

Dans la meme bibliotheque PremierDialogue, ecrivez dans un module le code 
suivant : 

rem Codell-Ol.odt bibli : PremierDialogue Modulel 
Option Explicit 

Sub appelerDialogueO 

Dim dig As Object, bibli As Object, monDialogue As Object 

' etape 1 : charger la bibliotheque en memoi re 

DialogLibraries.loadLibrary(" PremierDialogue") 

' etape 2 : recuperer l'objet bibliotheque 

bibli = DialogLibraries.getByName("PremierDialogue") 

' etape 3 : recuperer la boite de dialogue dans la bibliotheque 

monDialogue = bibli .getByName("Dialogl") 

dig = CreateUnoDialog(monDialogue) 1 etape 4 : creer le dialogue 
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' etapes 5 et 6 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 

MsgBox("Dialogue execute normal ement") 
else 

MsgBox("Dialogue annule") 
end if 
dig. dispose 
End Sub 

Executer un dialogue, meme simple, necessite plusieurs etapes : 

1 Charger en memoire d'OpenOffice la bibliotheque de dialogue contenant le dia- 
logue a utiliser. Ici la bibliotheque se trouve dans le document de la macro, et on 
utilise l'objet Basic DialogLibraries. 

2 Recuperer l'objet bibliotheque, une fois celle-ci chargee dans DialogLibraries. 
En effet, DialogLibraries contient plusieurs bibliotheques. 

3 Dans cette bibliotheque, recuperer le module de dialogue, qui est un objet mode- 
lisant la structure du dialogue. Une bibliotheque peut contenir plusieurs dialo- 
gues, chacun etant dans un module. Remarquez que le nom du module est le nom 
sur l'onglet dans l'EDI, et non pas de la propriete Nom du panneau de dialogue. 

4 Avec la fonction Basic CreateUnoDialog, creer une instance de dialogue a partir 
de l'objet modele de dialogue. 

5 Apres eventuellement diverses initialisations, lancer le dialogue avec sa methode 
execute. Celle-ci affiche la fenetre de dialogue et gere toutes les interactions de 
l'utilisateur jusqu' a sa fermeture. 

6 Tester la valeur renvoyee en fin d'execution pour savoir si le dialogue s'est deroule 
normalement ou a ete annule par l'utilisateur. Dans le premier cas, on analyse en 
general le contenu des controles afin de determiner les choix de l'utilisateur. 

7 Liberer la ressource de dialogue. 

Attention a la casse 

Veillez a bien respecter la casse pour le nom de la bibliotheque et le nom du dialogue. 

Les etapes 1 et 2 utilisent l'objet predefini DialogLibraries car nous utilisons une 
bibliotheque de dialogues qui se trouve dans le document. Mais il est possible d'uti- 
liser un dialogue situe dans Mes macros et boites de dialogue ou dans Macros et boTtes de 
dialogue OpenOffice.org. Ces bibliotheques sont accessibles depuis tout document 
comme depuis une macro situee dans Mes macros. Pour cela, on doit ajouter l'objet 
Global Scope, qui expose son propre objet DialogLibraries. Cela nous donne : 

CI obal Scope . Di al ogLi brari es . 1 oadLi brary (" Premi erDi al ogue" ) 

bi bl i = Gl obal Scope . Di al ogLi brari es . getByName ("Premi erDi al ogue") 
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Si vous omettez l'etape 1 (c'est-a-dire de charger la bibliotheque dans OpenOffice), 
cela marchera dans certaines situations, mais pas toujours dans d'autres. Pour eviter 
de vous arracher les cheveux, le mieux est de l'utiliser systematiquement, et meme si 
le dialogue se trouve dans la bibliotheque Standard. 

Les etapes 1 a 4 sont specifiques a une programmation avec OOoBasic. Avec 
d'autres langages de programmation, la methode est un peu differente. Reportez- 
vous au Developer's Guide ou a la section sur les boites a outils signalees a l'annexe A. 

La fonction dl g . Execute retourne une valeur numerique qui est une constante 
nommee. Ici, nous testons si le dialogue a ete ferme par un bouton de type OK. Si le 
dialogue est ferme par un bouton de type Annuler, ou en fermant la fenetre, la valeur 
de retour est : 

com . sun . star . ui . di al ogs . Executabl eDi al ogResul ts . CANCEL 



Methode 

Pour information, la valeur de retour pour OK est 1, mais ceci est un choix d'implementation. Utilisez le 
plus souvent possible la constante API et non la valeur numerique. Cette habitude amenera une plus 
grande facilite de relecture. 



La derniere instruction libere les ressources de dialogue. Elle n'est pas necessaire ici 
car la fin de la Sub va liberer toutes ses variables internes, mais c'est une bonne pra- 
tique de codage. 

Les etapes 1, 2, 3, 4 sont assez penibles lorsqu'on cree souvent des dialogues. Nous 
avons mis dans la bibliotheque Standard du meme document la fonction utilitaire 
CreerDialogue. 

rem Codell-Ol.odt bibli : Standard Modulel 
Option Explicit 

1 cree un dialogue et renvoi e son objet ( ou Null ) 

Function CreerDialogue(nomBibli As String, nomDialogue As String, _ 

Optional resident As Boolean) As Object 
Dim conteneur As Object, bibli as Object 

On Error GoTo errBibli 

if IsMissing(resident) then resident = False 
if resident then 

conteneur = GlobalScope.DialogLibraries 

el se 

conteneur = DialogLibraries 

end if 



Les bottes de dialogue 

Chapitre 1 1 



conteneur .loadLibrary(nomBi bl i ) 
bibli = conteneur. getByName(nomBi bl i ) 

CreerDialogue = CreateUnoDialog(bi bl i .getByName(nomDialogue)) 
On Error Goto 0 

Exit Function ' resultat : l'objet dialogue 

errBi bl i : 
Resume errBibli2 
errBi bl i 2 : 

On Error GoTo 0 ' resultat : Null 
End Function 

Cette fonction renvoie un objet dialogue. II suffit de lui dormer en argument le nom 
de la bibliotheque de dialogue, le nom du module de dialogue, et, si necessaire, un 
argument True si la bibliotheque se trouve dans Mes macros et boTtes de dialogue ou 
dans Macros et boTtes de dialogue OpenOffice.org. La macro d'appel est notablement 
simplifiee : 

rem Codell-Ol.odt bibli : PremierDialogue Module2 
Option Explicit 

Sub appelerDialogueO 
Dim dig As Object 

dig = CreerDialogue("PremierDialogue", "Dialogl") ' etape 1,2,3,4 
1 etapes 5 et 6 

if dig. execute = com. sun . star . ui . di alogs . Executabl eDialogResul ts .OK then 

MsgBox("Dialogue execute normalement") 
else 

MsgBox("Dialogue annule") 
end if 
dig. dispose 
End Sub 

Si la macro d'appel est situee dans une autre bibliotheque du document, les instruc- 
tions sont exactement les memes. Maintenant que nous savons comment appeler un 
dialogue, nous allons voir comment utiliser les controles de dialogue. Tous les exem- 
ples de dialogues utiliseront la fonction CreerDialogue, copiee dans la bibliotheque 
Standard du document afin quelle soit accessible depuis les autres bibliotheques. 
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Les principaux champs de saisie 

Jusqu'a present, nous n'avons qu'un dialogue equivalent a un MsgBox. Neanmoins, en 
ajoutant de nouveaux controles, nous allons multiplier les possibilites d'interaction 
avec l'utilisateur. 



La zone de texte 

Le controle Zone de texte (TextField) permet a l'utilisateur de saisir un texte. Dans 
un nouveau document, creez une nouvelle boite de dialogue avec : 

• un bouton OK ; 

• un bouton Annuler ; 

• un controle Etiquette intitule Votre Prenom ; 

_ • juste en-dessous, un controle Zone de texte : c'est l'icone ABC entouree d'un 
cadre. Dans la propriete Texte de ce controle inscrivez : Arthur. 

Vous obtenez une boite de dialogue similaire a celle de la figure 11-9. 

*1 



iTextFieldl — 

.. r^T— 3 
> iJ 

I 0 " 1 — 3 

Vous retrouvez les proprietes d'un controle Etiquette et de nouvelles proprietes. Uti- 
lisez l'icone de test pour voir leur utilite. Dans l'etat initial, le test vous montrera que 
vous pouvez modifier le champ zone de texte. 

Donnez a la propriete Longueur de texte max la valeur 5. Le champ n'affiche plus que 
Arthu et vous etes limite a 5 caracteres. Remettez la valeur zero pour ne pas avoir de 
limitation. Donnez a la propriete En lecture seule la valeur Oui . Durant le test, vous ne 
pouvez plus modifier le champ. Remettez la valeur Non. Donnez a la propriete Carac- 
tere pour mots de passe la valeur x. Le contenu du champ devient xxxxxx et tout ce 
que vous tapez en mode test est affiche avec le caractere x. Effacez ce caractere dans 
la propriete, le contenu reapparait en clair. 

Comment recuperer le texte saisi par l'utilisateur du dialogue ? Quelques instructions 
nouvelles vont suffire. 

rem Codell-02 . odt bibli : ZTexte Modulel 
Option Explicit 



Figure 11-9 

Dialogue avec 
une zone de texte 




Active. 



Les bottes de dialogue 

Chapitre 1 1 



Sub MainlO 

Dim dig As Object, champPrenom As Object, prenom As String 

dig = CreerDialogueC'Ztexte", "Dialogl") 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 

champPrenom = dlg.getControl ("TextFieldl") 

prenom = champPrenom. Text 

MsgBox("Votre prenom est : " & prenom) 
end if 
dig. dispose 
End Sub 

Nous recuperons d'abord dans la variable champPrenom l'objet controle Zone de texte, 
grace a la fonction CetControl de l'objet dig. La fonction getControl d'un objet dia- 
logue est tres utilisee car elle permet d'acceder a chacun des controles de la boite de 
dialogue. Le nom du controle passe en argument doit etre ecrit en respectant la casse. 
Le texte saisi par l'utilisateur (ou le texte initial, s'il n'a pas ete modifie) est obtenu 
avec la propriete Text sous la forme d'une variable String. Si le controle utilise la 
propriete Caractere pour mots de passe, le texte est recupere en clair. 

Les proprietes Plusieurs lignes et Barres de defilement vous seront utiles avec un champ 
zone de texte contenant de nombreuses lignes. En effet, ce champ affiche le contenu 
d'une variable String qui peut atteindre 65 535 caracteres. Vous pouvez introduire 
des retours a la ligne avec la touche Maj + Entree. 

Une zone de texte en lecture seule avec la propriete Plusieurs lignes est pratique pour 
afficher un texte d'information comme un mode d'emploi. Les avantages par rapport 
au controle Etiquette sont les suivants : les barres de defilement permettent de lire un 
texte tres long et l'utilisateur peut selectionner et copier tout ou partie de ce texte. 

Le texte a afficher peut etre determine par votre programme, comme le montre ce 
deuxieme exemple. 

rem Codell-02 . odt bibli : ZTexte Module2 
Option Explicit 

Sub Main2 

Dim dig As Object, information As Object 

Dim cr As String, blabla As String, n As Long 

cr = chr(13) 

blabla = "Voici un texte multi -ligne en lecture seule " & _ 

"ecrit par programme. Vous pouvez le selectionner et le copier" 

for n = 2 to 500 

blabla = blabla & cr & "Ceci est la ligne numero " & n 

next 
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dig = CreerDi al ogue("Ztexte" , "Dia"log2") 
information = dl g . getControl ("TextFi el dl") 
information. Text = blabla 
dig. execute 
dig. dispose 
End Sub 

Le retour a la ligne est realise avec le caractere chr(13). La chaine de caracteres pre- 
paree est copiee dans la propriete Text du controle avant d'afficher le dialogue. 
Comme il s'agit d'un simple affichage informatif, nous n'attendons rien de l'utilisa- 
teur et il est inutile de tester la valeur de retour de la methode execute. 

Le champ numerique 

Le controle Champ numerique (NumericField) sert a recuperer une valeur nume- 
rique saisie par l'utilisateur. Dans un nouveau document, creez une nouvelle boite de 
dialogue avec : 

• un bouton OK, un bouton Annuler, 

• un controle Etiquette intitule : Vot re Poids, 

123 • juste en-dessous, un controle Champ numerique : c'est l'icone 123 sur la barre 
flottante des controles. 

Le controle Champ numerique possede plusieurs proprietes specifiques. Remplissez- 
en quelques-unes : 

• Valeur = 70 ; 

• Valeur min = 3 ; 

• Valeur max = 250 ; 

• Decimales = 1. 

Figure 11-10 

Dialogue avec un Champ 
numerique 




Vous avez remarque que la fenetre des proprietes ajoute un nombre de decimales zero 
correspondant a la valeur courante de la propriete Decimales. Le caractere separateur de 
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decimales est bien une virgule, conformement a l'usage francais. Jouez avec les pro- 
prietes. Utilisez l'icone de test pour voir leur utilite. Modifiez a Oui la propriete 
Compteur : les triangles qui apparaissent servent a incrementer ou decrementer la valeur 
numerique. Vous obtenez une boite de dialogue similaire a celle de la figure 11-10. 

La valeur numerique fournie par l'utilisateur est recuperee de maniere tres similaire a 
un controle Zone de texte. 

rem Codell-02 .odt bibli : Znum Modulel 
Option Explicit 

Sub Mainl 

Dim dig As Object, champPoids As Object, lePoids As Double 

dig = CreerDialogue("Znum" , "Dialogl") 

if dig. execute = com. sun . star. ui .di alogs . Executabl eDialogResul ts .OK then 
champPoids = dlg.getControl ("NumericFieldl") 
lePoids = champPoids. Value 

MsgBox("Votre poids est : " & lePoids & " Kg") 
end if 
dig. dispose 
End Sub 

La propriete Val ue du controle Champ numerique est de type Doubl e, meme si vous 
avez seulement besoin d'un nombre entier. II existe d'autres controles numeriques 
specialises (heure, date, monetaire, masque) que nous etudierons bientot. 

La zone de liste 

Le controle Zone de liste (ListBox) permet a l'utilisateur de choisir un texte parmi 
plusieurs proposes. On dit aussi : choisir une entree parmi plusieurs. II existe plu- 
sieurs variations de zone de liste, qui ont beaucoup de points communs. 

La zone de liste simple 

Dans cette variante, l'utilisateur ne peut pas modifier les textes. Dans un nouveau 
document, creez une nouvelle boite de dialogue avec : 

• un bouton OK, un bouton Annuler, 

• un controle Etiquette intitule : Vot re destination, 




en-dessous, un controle Zone de liste. 
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Le controle Zone de liste possede plusieurs proprietes specifiques. Remplissez-en 
quelques-unes : 

• Entrees de liste = tapez ici 7 ou 8 noms de ville, avec un retour a la ligne entre cha- 
cune (touche Maj+Entree) ; 

• Deroulante = Oui ou Non ; 

• Nombre de lignes = 5 ; 

• Selection multiple = Non ; 

• Selection : cliquez la case a droite du champ, choisissez un des noms proposes, qui 
sera le choix initial. Pour ne pas imposer de choix, supprimez le contenu du 
champ Selection. 

Selon la valeur de la propriete Deroulante, vous obtenez une des deux boites de dia- 
logue de la figure 11-11. 



Figure 11-11 

Dialogue avec 

une zone de liste simple 




Utilisez l'icone Test pour voir le comportement dynamique du dialogue. Si vous 
mettez Non a la propriete Deroulante et augmentez suffisamment la hauteur du con- 
trole, toutes les lignes disponibles sont affichees, ce qui est parfois plus pratique pour 
l'utilisateur. La propriete Nombre de lignes n'est utile que pour une liste deroulante ; 
elle precise le nombre de lignes visibles dans la section deroulee. 

Tapez une lettre. S'il existe une entree commencant par cette lettre, elle s'affiche ; s'il 
en existe plusieurs, la premiere s'affiche. C'est une recherche incrementale : si vous 
tapez plusieurs lettres successivement, la premiere entree commencant par ces lettres 
s'affiche. Appuyez sur la barre Espace pour reprendre la recherche a zero. 

La recuperation du choix de l'utilisateur necessite plusieurs parametres. 

rem Codell-02 . odt bibli : Zliste Modulel 
Option Explicit 

Sub MainlO 

I Dim dig As Object, champDest As Object, dest As String, numdest As 
Integer 
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dig = CreerDialogue("Zliste", "Dialogl") 
champDest = dlg.getControl ("ListBoxl") 

champDest.SelectItemPos(l, True) ' selection eventuelle par programme 
if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 

dest = champDest. Sel ectedltem 

numdest = champDest. Sel ectedltemPos 

MsgBox("Rang choisi : " & numdest & " = " & dest) 
end if 
dig. dispose 
End Sub 

Le choix initial peut etre determine par programme, avec la methode 
Sel ectltemPos. Chaque choix a une position, le premier choix ayant la position zero. 
Vous devez effectuer l'initialisation avant d'afficher le dialogue, mais apres l'avoir 
cree. Le premier parametre de la methode est la position, le deuxieme precise si ce 
choix est selectionne ou non. 

La propriete Sel ectedltem est une chaine de caracteres contenant le choix de l'utili- 
sateur. La propriete Sel ectedltemPos est la position de ce choix dans la liste pre- 
sentee. II peut etre plus simple d'utiliser la position que la chaine de caracteres. 

Notre zone de liste comporte une liste fixee avec l'EDI. Plus loin dans ce chapitre, 
apres avoir explique des notions complementaires, nous montrerons comment gerer 
dynamiquement la liste de choix. 

La zone de liste a selection multiple 

Si dans le controle Zone de liste la propriete Selection multiple vaut Oui, l'utilisateur 
peut selectionner plusieurs lignes (en utilisant la souris comme dans l'explorateur de 
fichiers). La propriete Deroulante doit alors etre positionnee a Non. La propriete Selec- 
tion accepte de selectionner plusieurs noms. 

ROBUSTESSE 

Attention, l'utilisateur peut tout deselectionner, en faisant un Ctrl + die sur la derniere ligne encore 
selectionnee. II faut en tenir compte dans le codage. 

Lanalyse du choix utilisateur differe car on obtient un tableau des valeurs selection- 
nees au lieu d'une seule valeur. Les proprietes ont un nom quasiment identique : 
Item (element) devient Items pour marquer le pluriel. 

rem Codell-02 . odt bibli : Zliste Module3 
Option Explicit 
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Sub Main3() 

Dim dig As Object, champDest As Object 

Dim dest() As String, numdestO As Long, n As Long 

Dim listeSel As String, nbSelectDest As Long 

dig = CreerDi alogue("Zl i ste" , "Dialog3") 
champDest = dlg.getControl ("ListBoxl") 

champDest. SelectItemPos(l, True) ' selection eventuelle par programme 
champDest. Sel ectltemPos (4, True) 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 
dest = champDest. Sel ectedltems ' attention au pluriel ! 

numdest = champDest. Sel ectedltemsPos ' attention au pluriel ! 
if UBound(numdestO) < 0 then 

MsgBox("Vous n'avez choisi aucune destination") 
el se 

listeSel = "" 

for n = 0 to UBound(numdestO) 

listeSel = listeSel & numDest(n) & " : " & dest(n) & chr(13) 
next 

MsgBox(listeSel , 0, "Destinations choisies") 
end if 
end if 
dig. dispose 
End Sub 

Nous avons choisi de selectionner au depart deux lignes. On recupere un tableau de 
String avec Sel ectedltems, et un tableau d'lnteger avec Sel ectedltemsPos. La 
valeur minimale de l'index des tableaux est toujours zero, UBound fournit la valeur 
haute de l'index. Notez que UBound renvoie -1 si rien n'est selectionne. 

Plus loin dans ce chapitre, section « Modifier le contenu d'une zone de liste », se 
trouve le tableau 11-2 qui recapitule les methodes et proprietes de ce controle. 

La zone de liste combinee 

Avec le controle Boite combinee (ComboBox), l'utilisateur peut fournir un texte autre 
que ceux proposes. Creez une boite de dialogue identique a celle de la zone de liste 
simple, mais choisissez l'icone zone combinee. 

L'apparence du dialogue est identique a celle de la zone de liste simple 
(figure 11-11). 

Inscrivez dans la propriete Texte de l'EDI le nom d'une des destinations de la liste, 
par exemple Brest. Activez le test du dialogue et deroulez la liste : l'entree Brest est 
selectionnee. II en est de meme si vous saisissez le nom d'une des autres destinations. 
En la saisissant, vous verrez la recherche incrementale fonctionner. Vous pourriez 
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inscrire un nom absolument quelconque dans la propriete Texte, mais la liste de choix 
sera inchangee. L'equivalent en programmation est la propriete Text du controle. 

Les proprietes SelectedltemPos, SelectedltemsPos, Sel ectedltem, Sel ectedltems 
n'existent pas pour une zone de liste combinee ; la methode Sel ectltemPos non plus. 
La recuperation du choix de l'utilisateur se fait done de maniere differente de celle 
vue pour la zone de liste simple. 

rem Codell-02 .odt bibli : Zcombi Modulel 
Option Explicit 

Sub MainlO 

Dim dig As Object, champDest As Object, dest As String 

dig = CreerDialogue("Zcombi " , "Dialogl") 
champDest = dlg.getControl ("ComboBoxl") 

' champDest. Text = "Marseille" ' selection eventuelle par programme 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 

dest = champDest .Text 

MsgBox("Destination choisie : " & dest) 
end if 
dig. dispose 
End Sub 

Que l'utilisateur choisisse une des propositions ou en indique une autre, on recupere 
le texte de l'entree dans la propriete Text, de type Stri ng. La ligne de code en com- 
mentaire juste avant dig. Execute montre comment on peut, a l'execution, choisir la 
valeur par defaut. 

Si necessaire, le programmeur devra memoriser la nouvelle entree fournie par l'utili- 
sateur afin de construire dynamiquement la liste de choix pour un nouvel affichage 
du dialogue. Ceci sera developpe plus loin dans ce chapitre, section « Modifier le 
contenu d'une zone de liste combinee ». Vous y trouverez le tableau 11-4 qui recapi- 
tule les proprietes et methodes de la zone de liste combinee. 



Les cases a cocher 

Un controle Case a cocher (CheckBox) sert a rentrer une information binaire (oui, 
non). L'utilisateur change l'etat de la case en cliquant dessus. Creez une nouvelle 
boite de dialogue avec : 
• un bouton OK, un bouton Annuler, 
pr • trois controles Case a cocher ayant respectivement pour titre Cras, Italique, 
Souligne. 
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En selectionnant les trois controles Case a cocher dans l'EDI, donnez-leur la meme 
largeur, la meme hauteur et la meme PositionX. En utilisant la PositionY de chacun, 
espacez-les regulierement de haut en bas. Pour la case Italique, mettez la propriete 
Statut a : Selectionne. Vous obtenez la boite de dialogue de la figure 11-12. 



Testez la boite de dialogue : chaque case peut etre cochee ou decochee par l'utilisa- 
teur. Le codage ci-dessous vous montre une maniere, parmi d'autres, de savoir 
quelles cases ont ete cochees. 

rem Codell-02 . odt bibli : Cocher Modulel 
Option Explicit 

Sub MainlO 

Dim dig As Object, coche As Object 

Dim Cras As Boolean, Italique As Boolean, Souligne As Boolean 

dig = CreerDialogueC'Cocher", "Dialogl") 

if dig. execute = com . sun . star . ui . di al ogs . Executabl eDi al ogResul ts .OK 
then 

coche = dl g . getControl ("cocheGras") 

Gras = (coche. State = 1) 

coche = dig. getControl ("cocheltal i que") 

Italique = (coche. State = 1) 

coche = dig. getControl ("cocheSoul i gne") 

Souligne = (coche. State = 1) 

Print "Texte"; 

if Gras then Print " gras"; 

if Italique then Print " italique"; 

if Souligne then Print " souligne"; 

if not (Gras or Italique or Souligne) then Print " normal"; 

Print 
end if 
dig. dispose 
End Sub 




Figure 11-12 

Dialogue avec 
des cases a cocher 




I - Souligne 




La variable coche donne acces successivement a chaque controle Case a cocher ; la 
propriete State (Etat) du controle peut prendre une des valeurs : 
0 la case n'est pas cochee ; 
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1 la case est cochee ; 

2 etat « indetermine » ou « je ne sais pas ». 

L'etrange etat 2 ne peut etre atteint que si la propriete Statut triple a la valeur Oui. 
Dans ce cas, la coche apparait en grise. Dans la grande majorite des utilisations, 
Statut triple est laisse a Non, et State ne peut alors valoir que 0 ou 1. Notre codage 
remplit pour chaque controle une variable Bool ean a partir de State. Ces variables 
servent ensuite au traitement. 



Les cases de choix 1 parmi N 

Ces cases de choix (Opti on Button) sont appelees controle Bouton radio par reference 
aux vieux postes de radio sur lesquels, quand on enfoncait un bouton pour changer de 
gamme d'ondes, un autre bouton precedemment enfonce remontait par un effet 
mecanique. L'interet des Cases de choix 1 parmi N est que le systeme vous assure 
qu'une seule case sera active dans l'ensemble des cases de choix. 

Creez une nouvelle boite de dialogue avec : 
• un bouton OK, un bouton Annuler, 
q • quatre controles Case de choix 1 parmi N ayant respectivement pour titre : 
Celibatai re, Marie, Veuf, Divorce. 

En selectionnant les quatre controles Case de choix dans l'EDI, donnez-leur la 
meme largeur, la meme hauteur et la meme PositionX. En utilisant la PositionY de 
chacun, espacez-les regulierement de haut en bas. 

Sur une des quatre cases, modifiez la propriete Statut a Selectionne, afin d'assurer 
qu'une des possibilites est choisie au depart. 

Utilisez la fonction test pour changer a volonte la case choisie : il est effectivement 
impossible de selectionner plus d'une case. La figure 11-13 vous montre le resultat. 



Figure 11-13 

Dialogue avec 

des Cases de choix 1 parmi N 
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iCelibataire! 
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Pour mieux visualiser une liste de choix, il est recommande d'encadrer l'ensemble des 
cases de choix. II suffit de deposer un controle Zone de groupe (voir plus loin, sec- 
tion « L'aspect visuel des dialogues »), puis les cases de choix a l'interieur de celui-ci. 
Dans une boite de dialogue plus complete, vous pourriez avoir cette serie de cases 
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ainsi qu'une autre serie (par exemple pour le choix Homme ou Femme). Comment 
Basic va-t-il distinguer les deux ensembles de cases ? 

La reponse est la suivante : Basic regroupe dans un ensemble toutes les cases 

I parmi N qui possedent des valeurs successives de leur propriete Sequence d'activa- 
tion. La valeur de cette propriete est incrementee par l'EDI chaque fois qu'on depose 
un nouveau controle. Pour obtenir un deuxieme ensemble de cases, deposez sur le 
panneau de dialogue un deuxieme controle Zone de groupe, puis chacune des cases 
du deuxieme ensemble. La depose du controle Zone de groupe cree une disconti- 
nuite entre les sequences d'activation de la premiere serie et de la deuxieme serie. 
OpenOffice les traitera comme des series independantes. 

II est possible de modifier la valeur de la propriete Sequence d'activation d'un controle 
afin de le remettre dans une serie. Cependant, comme l'EDI renumerote alors une 
partie des controles, il faudra plusieurs essais pour obtenir l'ordre correct. A chaque 
essai, utilisez le test pour juger du resultat. En conclusion, prevoyez a l'avance vos 
controles 1 parmi N ; deposez-les successivement, deposez un controle Zone de 
groupe, puis deposez les controles de la serie suivante. 

Voici un exemple de code qui traite le dialogue de la figure 11-13. 

rem Codell-02 . odt bibli : ChoixlN Modulel 
Option Explicit 

Sub MainlO 

Dim dig As Object, choix As Object 

dig = CreerDialogue("ChoixlN", "Dialogl") 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 

choix = dl g . getControl ("_cel i b") 

if choix. State then Print "Vous etes celibataire" 

choix = dl g. getControl ("_mar") 

if choix. State then Print "Vous etes marie" 

choix = dl g . getControl ("_veuf") 

if choix. State then Print "Vous etes veuf" 

choix = dl g. getControl ("_div") 

if choix. State then Print "Vous etes divorce" 
end if 
dig. dispose 
End Sub 

Ici, la propriete State des controles de choix 1 parmi N nous donne directement une 
valeur binaire, True quand le controle est selectionne (et done que tous les autres du 
groupe sont False). A 1' execution de ce codage, une instruction Print et une seule 
sera executee si l'utilisateur a ferme la boite de dialogue par le bouton OK. 
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Zone de liste et choix 1 parmi N 

La zone de liste a selection unique et un groupe de cases de choix 1 parmi N remplissent la meme fonc- 
tion de deux manieres differentes, visuellement et dans le codage. Le choix de I'une ou I'autre des 
methodes depend du contexte et des contraintes d'interface utilisateur. 



Laspect visuel des dialogues 

L' aspect visuel et l'ergonomie d'un dialogue jouent un grand role dans l'aspect final 
d'une application. Ces deux points ne sont pas secondaires : l'enquete sur l'accident 
de surdosage d'irradiation dans un hopital d'Epinal a montre que des manipulateurs 
n'avaient pas compris la signification d'une case a cocher intitulee « DW » dans une 
boite de dialogue affichee par l'appareil. 

Presenter un dialogue ergonomique signifie qu'il doit paraitre clair, avec des possibi- 
lites et des comportements similaires a ceux que l'utilisateur peut avoir deja experi- 
mentes ailleurs. Regardez avec un ceil de concepteur de dialogues les divers panneaux 
affiches par les applications actuelles sous interface graphique. Observez en particu- 
lier les differents panneaux des options d'une application, qui vous donneront des 
exemples de dialogues complexes et penses pour etre ergonomiques. Ce chapitre pre- 
sente quelques conseils de base. 

Un dialogue clair 

Les utilisateurs ont parfois des ecrans plus petits que le votre. En regie generale et 
avec l'etat actuel du pare informatique, vos boites de dialogue doivent pouvoir tenir 
facilement dans un ecran SVGA (800 x 600 pixels). En fonction de la definition de 
votre ecran (par exemple 1280 x 1024), decoupez une feuille de papier representant 
une zone de 800 x 600 sur votre ecran afin de la comparer a l'affichage de votre boite 
de dialogue. 

Si votre dialogue affiche beaucoup de controles, decoupez-le en affichant des etapes 
successives plus simples (voir plus loin la section sur les dialogues a pages multiples). 

Quand vous avez des elements repetitifs, comme plusieurs boutons, ou plusieurs 
cases a cocher, veillez a les espacer regulierement et leur donner les memes dimen- 
sions. Si votre application emploie plusieurs boites de dialogue, prenez des dimen- 
sions identiques pour les controles de meme type, dans la mesure du possible. 

Pour chaque controle, essayez de trouver un libelle clair et precis pour l'utilisateur. 
Eventuellement ecrivez un texte explicatif dans la propriete Texte d ' ai de du con- 
trole, il s'affichera en bulk au passage de la souris. 
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La notion de focus 

Difficile de traduire le terme anglais focus ! Dans le contexte des systemes d'exploita- 
tion a fenetres, dont MS-Windows est le plus connu, un element visuel a le focus 
quand il est destinataire des touches du clavier. Pour une fenetre, ceci se manifeste 
par une couleur particuliere de l'en-tete. Cependant, dans une fenetre, chaque con- 
trole peut, tour a tour, prendre le focus. C'est alors ce controle qui recoit les saisies de 
l'utilisateur. 

Dans une fenetre de dialogue, le focus passe d'un controle a l'autre en cliquant sur un 
controle ou en appuyant sur la touche Tab ou Maj + Tab, ou parfois en appuyant sur 
une autre touche. Un controle en focus se distingue par certaines modifications visi- 
bles, par exemple un champ texte devient selectionne dans une couleur soutenue, ou 
le libelle d'un bouton est encadre en pointille. Quand un bouton a le focus, appuyer 
sur la touche Entree declenche celui-ci. 

L'ordre dans lequel les controles sont parcourus avec des tabulations successives est 
celui des valeurs croissantes de la propriete Sequence d'activation. Les valeurs succes- 
sives sont choisies par l'EDI dans l'ordre de pose des controles sur la boite de dia- 
logue. En imposant des valeurs adequates, vous pouvez choisir un ordre de parcours 
quelconque. Cependant, comme l'EDI modifie parfois l'ordre d'autres controles 
pour garder une coherence, plusieurs modifications seront peut-etre necessaires. 
Enfin, n'oubliez pas que la propriete Sequence d'activation est utilisee pour regrouper 
les controles Case de choix 1 parmi N. 

La propriete Tabulation indique si le controle peut ou non recevoir le focus. En 
general, un controle en lecture seule ne recoit pas le focus. 

Le fichier Codell-01. odt du Zip telechargeable contient dans la bibliotheque Focus 
un dialogue avec quelques controles, reproduit dans la figure 11-14. Verifiez par 
vous-meme ce qui est decrit ici, soit avec la fonction de test du dialogue, soit en exe- 
cutant la macro du module Basic associe. 



Figure 11-14 

Exemple de dialogue 
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II est parfois utile apres un traitement de positionner le focus sur le controle de dia- 
logue qui devrait logiquement etre modifie. La methode est simple : 

monControl .setFocus 

Le bouton par defaut 

Dans l'EDI, il existe une propriete de bouton appelee Bouton par defaut. Dans un 
dialogue comportant plusieurs boutons, si vous mettez a Oui cette propriete pour un 
(et un seul) des boutons, celui-ci sera declenche si vous appuyez sur la touche Entree. 

Neanmoins, ceci se fera a condition que le focus ne soit sur aucun des boutons. Typi- 
quement, le focus est sur un champ de saisie que vous venez de remplir. Si le focus est 
sur un des boutons, il sera declenche avec la touche Entree, meme s'il n'est pas le 
bouton par defaut. Cette condition illustre aussi l'importance de l'ordre des con- 
troles, qui gouverne la succession des focus. 

Dans la figure 11-14, le bouton Annuler est le bouton par defaut, reconnaissable par 
une ombre portee plus visible que sur les autres boutons. 

S'il n'y a pas de bouton par defaut et si le focus n'est pas sur un des boutons, appuyer 
sur la touche Entree ne declenche aucun bouton. 

Lettre acceleratrice 

Sur chaque bouton ordinaire (c'est-a-dire ayant le type Par defaut), une lettre de son 
libelle est soulignee. II suffit de taper celle-ci pour amener le focus sur ce bouton, a 
condition qu'il soit deja sur un autre bouton. Par defaut, OpenOffice.org choisit la 
lettre acceleratrice en fonction des libelles des boutons. A la conception du dialogue 
vous pouvez imposer la lettre acceleratrice d'un bouton en la faisant preceder par le 
caractere tilde ~. 

Peut-on de la meme maniere mettre directement le focus sur un controle a remplir ? 
La reponse est oui, mais le principe est subtil. Dans le dialogue de la figure 11-14 
vous avez peut-etre remarque que les controles Etiquette ont, eux aussi, une lettre 
soulignee. Si le focus est sur un bouton et que vous tapez cette lettre, le focus passe sur 
le controle situe en-dessous du controle Etiquette. En fait, le focus passe au controle 
dont la propriete Sequence d'activation a une valeur immediatement superieure a celle 
du controle Etiquette. Pour arriver a cela nous avons depose successivement un con- 
trole Etiquette, un controle Zone de texte, un controle Etiquette, un controle Zone 
de liste. Si vous ne souhaitez pas voir de lettre acceleratrice sur un controle Etiquette, 
dans l'EDI mettez a Oui la propriete Pas d'etiquette de ce controle. 
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Les elements visuels 

Ces controles sont totalement passifs, leur utilite est entierement visuelle. lis vous 
aideront a structurer des boites de dialogue complexes dans lesquelles l'utilisateur 
reperera facilement les elements principaux. 

La zone de groupe 

Le controle Zone de groupe sert a encadrer plusieurs controles qui ont un rapport 
entre eux. On utilise la zone de groupe pour entourer des controles Case a cocher ou 
des controles Case de choix 1 parmi N. Cependant, elle peut aussi bien entourer un 
melange de controles de differents types qui servent a definir les parametres d'une 
fonctionnalite. 

Attention Un cadre, pas un conteneur 

Le controle Zone de groupe ne contient pas les elements qu'il encadre ; il n'a pas de rapport hierarchique 
avec les autres controles de la boTte de dialogue. 

Dans une boite de dialogue, deposez un controle Zone de groupe. 

Redimensionnez-le. Pour le selectionner, cliquez sur la ligne du cadre, a gauche, a 
droite, en bas, mais pas en haut. Pour le deplacer, posez votre souris sur une ligne du 
cadre et glissez. 

Si vous effacez le texte de la propriete Etiquette, vous obtenez un rectangle simple. 

Placez plusieurs controles a l'interieur du cadre de la zone de groupe. Deplacez ensuite 
la zone de groupe : les autres controles restent sur place ! En effet, la zone de groupe est 
seulement un element visuel, elle n'a aucune influence sur les autres controles. 

Les lignes horizontale et verticale 

Le controle Ligne horizontale separe deux regions haute et basse de la boite de dia- 
logue. La propriete Etiquette de ce controle permet d'ajouter un texte sur la gauche de 
la ligne. 

Le controle Ligne verticale separe deux regions gauche et droite de la boite de dia- 
logue. Ici en revanche, la propriete Etiquette n'est pas utilisee. 

Le dialogue de la figure 11-14 utilise ces deux controles. 
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Les champs de saisie specialises 

Nous allons maintenant aborder des controles plus elabores, disposant de nouvelles 
proprietes. Pour des raisons d'implementation, des proprietes peuvent etre presentes 
dans plusieurs controles mais actives seulement dans certains. 

Le champ de date 

Y| Le controle de champ Date (DateFi el d) est utilise pour saisir une date situee entre le 
l er janvier 1600 et le l er janvier 9999. Deposez sur une boite de dialogue un controle 
de champ Date. 

Les proprietes Date, Date min, Date max permettent d'initialiser une date et de deli- 
miter i'eventail des dates acceptees. La propriete Format de date vous offre de nom- 
breuses variations de format, dont celle de la figure 11-15. 



Figure 11-15 

Dialogue avec un champ 
Date en format long 




II est a noter que l'utilisateur peut remplir ce champ avec un format different, mais 
qu'il sera affiche avec le format du dialogue quand l'utilisateur passera a un autre con- 
trole du dialogue, par exemple en tapant la touche Tab. Parmi les formats acceptes 
dans la saisie, une date comme 14 juillet 75 est aussi acceptee. 

La propriete Deroulante a la particularite d'afficher un petit calendrier quand l'utilisa- 
teur clique sur le triangle noir. La figure 11-16 montre 1' aspect du dialogue et du 
calendrier. 



Figure 11-16 

Dialogue avec un champ 
Date deroulant 
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Vous remarquerez la position du curseur sur la gauche du champ. On peut posi- 
tionner le curseur par un clic de souris. Le calendrier quant a lui offre de nombreuses 
possibilites : 

• cliquer sur la date du mois affiche ; 

• changer de mois en cliquant sur les fleches droite ou gauche ; 

• choisir l'annee precedents ou suivante en cliquant sur l'annee, ce qui donne 
ensuite le choix du mois ; 

• imposer la date d'aujourd'hui. 

La propriete Compteur permet d'incrementer ou de decrementer facilement le jour, le 
mois ou l'annee, selon la position du curseur (figure 11-17). 



Figure 11-17 

Dialogue avec un champ 
Date compteur 




II est meme possible de combiner l'affichage deroulant et l'affichage compteur. 

Sur le plan du codage, nous devons resoudre une petite difficulte. La propriete Date 
obtenue du controle est un entier Long dont la valeur, affichee sous forme decimale, 
est une juxtaposition des chiffres d'annee, mois, jour. Par exemple, le 
28 decembre 2003 est represente par la valeur 20031228. Ce format est une date ISO. 
Basic est capable de le convertir au format interne de type Date avec la fonction 
CDateFromlSO. 

Le codage necessaire a la recuperation de la date saisie est finalement assez simple. 

rem Codell-03 . odt bibli : Date Modulel 
Option Explicit 

Sub demanderDateO 

Dim dig As Object 

Dim champDate As Object, datelSO As Long, laDate As Date 

Dim a As Integer, m As Integer, j As Integer 

dig = CreerDialogue("Date" , "Dialogl") 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 
champDate = dlg.getControl ("DateFieldl") 
datelSO = champDate. Date 
laDate = CDateFromlSO(datelSO) 
print datelso, laDate 
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end if 
dig. dispose 
End Sub 



Le champ horaire 

|iT| Le controle de champ Horaire (TimeField) est utilise pour saisir une heure (et 
minutes, secondes). Deposez sur une boite de dialogue un controle de champ horaire. 

Les proprietes Heure, Heure min, Heure max permettent d'initialiser l'heure et de deli- 
miter l'eventail des heures acceptees. 

La propriete Format d'heure vous offre quelques variations de format, dont deux for- 
mats a l'anglaise. II est a noter que l'utilisateur peut remplir ce champ avec un format 
different, mais qu'il sera affiche avec le format du dialogue quand l'utilisateur passera 
a un autre controle, par exemple en tapant la toucheTab. La figure 11-18 montre 
l'aspect du dialogue. 



Vous remarquerez la position du curseur sur la droite du champ. On peut positionner le 
curseur par un clic de souris. La propriete Compteur permet d'incrementer ou de decre- 
menter facilement l'heure, les minutes ou les secondes, selon la position du curseur. 

Sur le plan du codage, nous devons ici aussi resoudre une petite difficulte. La pro- 
priete Ti me obtenue du controle est un entier Long dont la valeur, affichee sous forme 
decimale, est une juxtaposition des chiffres d'heures, de minutes, de secondes, et d'un 
emplacement pour les centiemes de secondes, non utilises. Par exemple, 
15h 57min 38s est representee par la valeur decimale : 15573800. 

Ce format n'est pas utilisable tel quel, et Basic ne nous offre pas de fonction de con- 
version. Nous en creons une ConvHeure, qui renvoie une heure au format interne a 
partir de la valeur de la propriete Time. 

rem Codell-03 . odt bibli : Heure Modulel 

' conversion du champ Time en heure, minute, seconde 
Function ConvHeure (champ As Long) As Date 
Dim chaineHeure As String 

Dim hr As Integer, mn As Integer, sec As Integer 



Figure 11-18 





Construire des applications avec OpenOffice.org 

QUATRIEME PARTIE 



' pour tranter les cas heure=0 et heure=mi nute=0 

' on ajoute un nombre pour forcer 1 'apparition des zeros 

chaineHeure = Str(champ +100000000) 

hr = CInt(Mid(chaineHeure, 3, 2)) 

mn = CInt(Mid(chaineHeure, 5, 2)) 

sec = CInt(Mid(chaineHeure, 7, 2)) 

ConvHeure = TimeSerial (hr , mn , sec) 

End Function 

Le codage necessaire a la recuperation de l'heure saisie est lui-meme assez simple. 

rem Codell-03 . odt bibli : Heure Modulel 
Option Explicit 

Sub demanderHeure() 
Dim dig As Object 

Dim champHeure As Object, uneHeure As Date, HeureBrute As Long 

dig = CreerDialogue("Heure" , "Dialogl") 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 

champHeure = dlg.getControl ("TimeFieldl") 

HeureBrute = champHeure. Time 

' convertir le format special en heure interne 

uneHeure = ConvHeure(HeureBrute) 

print HeureBrute, uneHeure 
end if 
dig. dispose 
End Sub 



Le champ monetaire 

^ Le controle de champ Monetaire (CurrencyField) est utilise pour saisir la valeur 
numerique d'une somme monetaire. Deposez sur une boite de dialogue un controle 
de champ monetaire. 

En plus des proprietes classiques (Valeur, Valeur min, Valeur max), il existe une serie de 
proprietes permettant de formater le champ affiche : 

• Decimales ; 

• Separateur de milliers ; 

• Symbole monetaire ; 

• Placer le symbole avant le nombre. 

Saisissez un nombre de maniere classique dans une des proprietes Valeur. Au passage 
a une autre propriete, la valeur saisie sera formatee conformement a l'ensemble des 
proprietes de formatage. La figure 11-19 montre un exemple de dialogue avec 
champ Monetaire. 
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Figure 11-19 

Dialogue avec un champ 
Monetaire 




Au niveau du codage, la valeur du champ monetaire est recuperee avec la propriete 
Value, qui est de type Double (et non pas Currency). 

rem Codell-03 .odt bibli : Monnaie Modulel 
Option Explicit 

Sub MainlO 

Dim dig As Object, champMonnaie As Object, Prix As Double 

dig = CreerDialogue("Monnaie" , "Dialogl") 

if dig. execute = com. sun . star . ui . di alogs . Executabl eDialogResul ts .OK then 
champMonnaie = dlg.getControl ("CurrencyFieldl") 
prix = champMonnaie. Value 

MsgBox(Format(prix*6. 55957, "0.00 FF"), 0, "Francs francais") 
end if 
dig. dispose 
End Sub 



Le champ masque 

Comme un masque qui ne decouvre que certaines zones, le controle de champ 
Masque (PatternField) est utilise pour remplir des zones dans un champ de saisie. 
Dans chacune de celles-ci, l'eventail des caracteres acceptes peut etre limite. Par 
exemple, on utilisera un champ masque pour demander un numero de compte ban- 
caire comprenant des chiffres et une lettre. Un exemple d'utilisation est represente 
sur la figure 11-20. 



Figure 11-20 

Dialogue avec un champ 
Masque 



Deposez sur une boite de dialogue un controle de champ Masque. 

La propriete Texte de l'EDI est la valeur initialement affichee dans le controle. 
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Attention 

Ce texte sera repris tel quel comme resultat si I'utilisateur ne le modifie pas. Saisissez done un format 
correct. 



Le fonctionnement du controle masque depend de trois parametres essentiels. La 
propriete Masque de saisie (PatternField) indique, caractere par caractere, quels 
ensembles de valeurs sont acceptables (voir le tableau 11-1). 

Tableau 11-1 Lettres du masque de saisie 



L 


Litteral 


Reproduire le caractere correspondant du masque litteral. 


N 


Numerique 


Seuls les chiffres 0 a 9 sont acceptes. 


a 


Alphabetique 


Les lettres minuscules ou majuscules seules sont acceptees, y compris les 
accentuees. 


A 


Alphabetique 


Comme a, mais le caractere est affiche en majuscule. 


c 


Caractere 


Lettre ou chiffre ; equivalent a : a ou N. 


C 


Caractere 


Comme c, mais le caractere est affiche en majuscule. 


X 


Caractere 


Caractere quelconque, y compris les ponctuations, etc. 


X 


Caractere 


Comme x, mais le caractere est affiche en majuscule. 



La propriete Masque litteral indique, caractere par caractere, ce qui doit etre affiche par 
defaut dans le champ. Si le caractere correspondant du Masque de saisie vaut L, le carac- 
tere du Masque litteral est reproduit tel quel, et restera fige. Sinon, on va en general 
mettre un caractere espace ou souligne pour indiquer un emplacement a remplir. 

La propriete Verification de Format fonctionne ainsi : 

• Si la valeur est Oui, l'affichage dans le champ est reformate selon les autres para- 
metres au cours de la frappe ; la valeur recuperee par la macro correspond a ce qui 
est affiche. 

• Si la valeur est Non, l'affichage est reformate seulement quand le focus passe sur un 
autre controle ; la valeur recuperee par la macro correspond a ce qui a ete tape, 
non a ce qui est affiche. 

Ceci sera plus clair en variant les parametres sur un exemple. La valeur resultante du 
controle est recuperee en codage dans les proprietes Text et String, du type String. 
Un codage typique se presente ainsi : 



rem Codell-03 . odt bibli : Masque Modulel 
Option Explicit 
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Sub MainlO 

Dim dig As Object, champMasque As Object, saisie As String 

dig = CreerDialogueC'Masque", "Dialogl") 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 
champMasque = dlg.getControl ("PatternFieldl") 
saisie = champMasque. String ' champMasque .Text est equivalent 
print saisie 

end if 

dig. dispose 

End Sub 



Le champ formate 

Le controle de champ Formate (FormattedField) offre une grande variete de for- 
mats d'affichage, dont ceux vus dans les champs Date, Horaire et Monetaire, d'autres 
formats qui lui sont specifiques, et la possibilite de creer sa propre variante de format. 
Evidemment, cette puissance implique une plus grande difficulte de maitrise. 

Nous allons presenter ici seulement des formats specifiques au champ Formate et qui 
sont predefinis. Les differents exemples sont realises et utilises de maniere similaire, 
et nous expliquerons essentiellement le premier. Sur une boite de dialogue, deposez 
^ des boutons OK et Annuler, et l'icone Champ Formate. 

Format Date 

Le panneau Propriete (figure 11-21) vous permet de definir le type de format, la 
valeur par defaut ainsi que les valeurs minimale et maximale. 



Figure 11-21 

Panneau des proprietes du 
controle champ Formate 
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En cliquant sur l'icone a droite du champ Formatage, vous retrouvez le panneau de 
dialogue du formatage de cellule dans Calc, onglet Nombre. 



Methode Initialiser le format 

Quel que soit le type de format, veillez a donner une valeur initiale a la propriete Valeur. Activez aussi la 
verification de format. 



Utilisez la fonction de test pour obtenir la figure 11-22. 



Figure 11-22 

Dialogue avec un champ 
Formate en Date 



Date et heure 



|3l decembre 1999 23:59:59 
Annuler 



Effacez tout le champ, puis remplissez-le avec 15/8/6, et appuyez sur la touche Tab. 
L'affichage change pour representor la date/heure dans le format requis. L'utilisateur 
peut employer divers formats de saisie, par exemple une heure sous la forme 1:2 pm 
qui sera interpreted comme 13h 2min Os ; il peut aussi modifier une partie de l'affi- 
chage. Cependant, la combinaison de la date et de l'heure dans un seul champ est en 
general moins comprehensible que deux champs separes. 

Au plan de la programmation, le resultat affiche est disponible dans la propriete Text 
du controle. Obtenir la valeur de date est plus complexe, car elle est fournie par la 
propriete EffectiveValue, qui elle-meme provient du modele du controle. De plus, 
le type de la valeur obtenue depend du format utilise. Aussi utiliserons-nous dans nos 
exemples un type Variant et des fonctions de conversion quand ce sera necessaire. 



rem Codell-03 . odt 
Option Explicit 



bibli : Formate Modulel 



Sub FormatDateO 
Dim dig As Object 

Dim ChampValeur As Object, chmod As Object, valeur As Variant 

dig = CreerDialogue("Formate", "Dialogl") 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK 
ChampValeur = dlg.getControl ("FormattedFieldl") 
chmod = ChampValeur. Model 
valeur = chmod. EffectiveValue 

MsgBox("Date et heure : " & CDate(valeur) & chr(10) & _ 



then 
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"Date formatee : " & ChampValeur.Text & chr(10) & _ 
"Date Min =" & CDate(chmod . Ef fectiveMin) & chr(10) & _ 
"date Max =" & CDate(chmod . Ef fectiveMax) ) 

end if 

dig. dispose 

End Sub 

La valeur est recuperee sous forme de Double que nous devons convertir en Date 
pour l'affichage. Les valeurs extremes acceptees sont accessibles dans les proprietes 
EffectiveMin et Ef fectiveMax du modele du controle. Faites des essais avec diffe- 
rentes valeurs et differents formats. Nous avons trouve un bogue dans certains cas 
(Issue 91334). 

Format Pourcentage 

La figure 11-23 montre comment la valeur 0,25 est affichee au format Pourcentage : 



La programmation est identique au cas precedent. Lexemple est simplifie : 

rem Codell-03 .odt bibli : Formate Module2 
Option Explicit 

Sub FormatPourcentO 

Dim dig As Object, ChampValeur As Object, valeur As Variant 

dig = CreerDialogue("Formate" , "Dialog2") 

if dig. execute = com. sun . star . ui . di alogs . Executabl eDialogResul ts .OK then 
ChampValeur = dlg.getControl ("FormattedFieldl") 
valeur = ChampValeur. Model .EffectiveValue 

MsgBox("Valeur reelle : " & Format (valeur, "0.000") & chr(10) & _ 
"Valeur affichee : " & ChampValeur.Text ) 
end if 
dig. dispose 
End Sub 

Ici, il n'est pas necessaire de convertir la valeur, quoique cela ne ferait aucun mal. 



Figure 11-23 

Dialogue avec un champ 
Formate en Pourcentage 





Hausse des prix 
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Format Monetaire 

Nous avons choisi un format monetaire qui affiche en rouge les valeurs negatives. 
Evidemment, sur la figure 11-24, c'est difficile a voir. 



Figure 11-24 

Dialogue avec un champ 
Formate en Monetaire 



r 




Credit / Debit 

I - l 00,35 EUR 






_ 




_ 



La valeur resultante est encore un Doubl e. La programmation est identique a celle du 
format Pourcentage. 

Format Booleen 

Ce format affiche en clair VRAI ou FAUX (si on a choisi le francais comme langue de 
format) selon que le contenu est True ou False (voir la figure 11-25). Les valeurs 
admissibles en entree sont les textes VRAI ou FAUX, ou un nombre. Un nombre diffe- 
rent de zero est equivalent a VRAI, un texte non reconnu ou la valeur zero sont equi- 
valents a FAUX. 

Figure 11-25 

Dialogue avec un champ 
Formate en Booleen 



La valeur resultante est une valeur numerique zero ou un, que nous convertissons en 
un type Boolean. 

rem Codell-03 .odt bibli : Formate Module4 

' -- partie specifique 

MsgBox("Valeur reelle : " & CBool (valeur) & chr(10) & _ 
"Valeur affichee : " & ChampVal eur .Text ) 

Sur le plan visuel et ergonomique, la case a cocher ou la zone de liste simple sont 
bien plus utilisees que le champ Formate Booleen. 
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Format Fractionnaire 

II s'agit d'une presentation utilisee dans les pays anglo-saxons. Un nombre reel est 
represente par sa partie entiere et une fraction correspondant approximativement a la 
partie fractionnaire. La figure 11-26 montre la representation du nombre 3 , 3. 



Figure 11-26 

Dialogue avec un champ 
Formate en Fractionnaire 




Faites le calcul : 
3 + 2/7 = 3,285714285714285714 

Si vous saisissez la valeur 3 , 3 et cliquez sur OK, vous obtiendrez le resultat ci-dessus, 
et non pas ce que vous avez saisi ! En revanche, le resultat est exact pour 5,25 et 
d'autres valeurs. 

Par une bizarrerie d'implementation, si vous indiquez 3 , 3 comme valeur initiale dans 
l'EDI et si vous acceptez cette valeur, vous recuperez bien 3,3. 

La valeur obtenue par programmation est de type Doubl e. La programmation est iden- 
tique a celle du format Pourcentage. En pratique, a cause de son manque de precision, 
le champ Formate Fractionnaire sera plutot limite a des affichages en lecture seule. 

La selection de fichiers 

Le controle Selection de fichiers (FileControl) est assez primitif, mais peut etre 
utile pour rechercher facilement un fichier. Sur une boite de dialogue, deposez une 
icone Selection de fichiers. 

En augmentant suffisamment sa largeur, vous obtiendrez un dialogue similaire a 
celui de la figure 11-27. 



Figure 11-27 

Dialogue avec un champ 
Selection de fichiers 
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La propriete Texte sert a indiquer un repertoire existant comme point de depart 
d'exploration. Utilisez le mode test pour voir comment fonctionne le controle. Cli- 
quez sur le bouton Parcourir... pour explorer un disque de votre PC. Dans le panneau 
de recherche le champ Fichiers de type n'est pas employe, mais on peut taper un filtre 
de recherche (comme * . odt) dans le champ Nom du fichier, puis cliquer sur le bouton 
Ouvrir pour le prendre en compte. 

Par programmation, vous utiliserez la propriete Text du controle pour recuperer le 
chemin du fichier choisi. Ce chemin est presente dans le format natif du systeme 
d'exploitation. 

rem Codell-03 . odt bibli : Fichiers Modulel 
Option Explicit 

Sub MainlO 

Dim dig As Object, champFich As Object, cheminFich As String 

dig = CreerDialogue("Fichiers" , "Dialogl") 
champFich = dlg.getControl ("FileControll") 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 

cheminFich = champFi ch .Text 

MsgBox(chemi nFich) 
end if 
dig. Dispose 
End Sub 

Nous verrons avec les services de dialogues de l'API une autre methode de recherche 
de fichiers offrant plus de possibilites. 

Le controle Image ou controle Picto 

Le controle Image, ou controle Picto (imageControl), sert a afficher un fichier 
image. La plupart des types de fichiers sont reconnus. Deposez sur une boite de dia- 
logue un controle Picto. Dessinez-le suffisamment grand. 

Deposez ensuite seulement un bouton OK, puisqu'il s'agit d'un simple affichage. Les 
proprietes specifiques au controle Image sont : 

• Image : donne acces a une fenetre de recherche de fichier ; une fois choisi, celui-ci 
s'affiche dans le controle. 

• Echelle : avec la valeur par defaut, Oui, l'image est redimensionnee pour couvrir 
totalement la surface du controle, en reduisant ou augmentant la taille. Si les pro- 
portions hauteur sur largeur sont differentes de celles de l'image, l'affichage sera 
deforme. Avec la valeur Non, l'image est affichee telle quelle ; si elle est plus 
grande que le controle, une partie sera visible, si elle est plus petite, elle ne cou- 
vrira pas toute la surface du controle. 
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Choisissez done une image, grande ou petite. Vous obtiendrez un dialogue similaire 
a celui de la figure 11-28. 



Figure 11-28 

Dialogue avec un controle 
Image 




Nous allons choisir par programme le fichier qui sera affiche dans le controle Image. 
Pour cela, nous afficherons un premier dialogue pour recuperer le chemin d'acces au 
fichier. C'est le codage vu dans la section « La selection de fichiers ». 

rem Codell-03 .odt bibli : Fichiers Module2 
Option Explicit 

Sub Main2() 

Dim dig As Object 

Dim champFich As Object, cheminFich As String, champlmage As Object 

dig = CreerDialogue("Fichiers" , "Dialogl") 
champFich = dlg.getControl ("Fi 1 eControl 1") 

if dig. execute = com. sun . star . ui . di alogs . Executabl eDialogResul ts .OK then 
cheminFich = champFich. Text 

dig. dispose ' liberer le dialogue 1 

dig = CreerDialogue("Fichiers", "Dialog2") 

champlmage = dlg.getControl ("ImageControl 1") 

champlmage. Model . ImageURL = ConvertToURL(chemi nFi ch) 

dig. execute ' simple affichage 
end if 
dig. dispose 
End Sub 

Dans la deuxieme partie du codage, nous reutilisons la variable dl g pour creer le 
deuxieme dialogue qui utilisera l'URL du fichier d'image. Auparavant, la methode 
di spose a libere les ressources du premier dialogue. 

Au niveau programmation, on accede a la propriete Image de l'EDI avec la propriete 
ImageURL de l'objet Model du controle Image. 

La propriete ImageURL doit contenir, vous l'aviez devine, une URL. Comme nous 
avons recupere un chemin de fichier au format natif, nous utiliserons la fonction 
Basic de conversion au format URL. 
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Enfin, puisque notre deuxieme dialogue est un simple affichage, il suffit d'appeler la 
fonction execute sans utiliser 1'information quelle renvoie. 

Les barres de defilement 

Les controles Barre de defilement (Scroll Bar) sont horizontales ou verticales. Ces 
controles peuvent servir a creer des ascenseurs pour faire defiler le contenu d'une 
boite de dialogue, mais ceci est assez complexe et rarement utile. 

Nous utiliserons ces controles comme des glissieres de reglage semblables aux dispo- 
sitifs utilises dans les amplificateurs Hi-Fi pour ajuster les graves et les aigus. On 
peut ainsi modifier de maniere analogique (par glissement de la souris) la valeur 
d'une variable, par exemple commandant un niveau sonore. 

[gj Deposez sur une boite de dialogue des boutons OK et Annuler, et une icone Barre de 
defilement horizontale. 

Affectez a la propriete Valeur de defilement la valeur 20. Vous obtenez le dialogue de 
la figure 11-29. 



Figure 11-29 

Dialogue avec un controle 
Barre de defilement 




L'utilisateur fait glisser le curseur de defilement de diverses manieres : 

• avec sa souris, en faisant glisser le curseur ; 

• en cliquant sur les fleches aux extremites de la barre (petit deplacement) ; 

• en cliquant sur la zone de deplacement de la barre (grand deplacement) ; 

• en appuyant sur les touches de deplacement droite et gauche (petit deplacement) ; 

• en appuyant sur les touches de saut de page (grand deplacement). 

Les valeurs de petit et grand deplacement sont initialisees dans l'EDI avec les pro- 
prietes Petit changement et Grand changement respectivement. 

Au plan de la programmation, la valeur correspondant a la position du curseur se 
trouve dans la propriete Val ue, qui est du type Doubl e. 

rem Codell-03 . odt bibli : Reglage Modulel 
Option Explicit 



Sub MainlQ 
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Dim dig As Object, champRegl age As Object, reglage As Double 

dig = CreerDialogue("Reglage" , "Dialogl") 

if dig. execute = com. sun . star . ui . di alogs . Executabl eDialogResul ts .OK then 

champRegl age = dl g . getControl ("Scrol 1 Barl") 

reglage = champRegl age. Value 

Print "Regler le volume a : " & reglage & "%" 
end if 
dig. dispose 
End Sub 



La barre de progression 

Le controle Barre de progression (ProgressBar) sert a presenter une graduation pro- 
portionnelle a une valeur. C'est l'equivalent d'une jauge analogique. 



POUR LES EXPERTS Execution parallele de lignes de codes 

Basic ne permet pas de gerer plusieurs threads. II n'est done pas possible d'afficher une boTte de dialo- 
gue avec une barre de progression qui avancerait a mesure de I'avancement d'un autre processus Basic 
execute en parallele. L'exemple que nous presentons utilise une particularite des routines de traitement 
d'evenement sur un controle. 



i Dans une boite de dialogue, deposez un bouton ordinaire, un bouton Annuler et un 
bouton OK. Pour ce dernier, mettez a Non la propriete Active. Ajoutez enfin l'icone 
d'une Barre de Progression. 

Donnez a la propriete Valeur de progression la valeur 10. La barre de progression appa- 
rait. II est possible de choisir une autre couleur pour le fond du controle et pour les bar- 
rettes de progression. Les valeurs Valeur de progression min et max de la progression sont 
par defaut zero et 100. La figure 11-30 montre 1' aspect de la barre de progression. 

Figure 11-30 

Dialogue avec un controle 
Barre de progression 
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La difficulte de programmation est de simuler un travail qui fait avancer peu a peu la barre 
de progression. Pour la surmonter, nous utiliserons les possibilites ofFertes par la gestion 
des evenements. Void la totalite du code que nous allons ensuite expliquer en detail. 

rem Codell-03 . odt bibli : Progres Modulel 
Option Explicit 

Private dig As Object 

Sub BarreProgressionO 

dig = CreerDialogue("Progres", "Dialogl") 

if dig. execute <> com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 
MsgBox "annulation du travail" 

' ici il faudrait annuler ce qu'on a commence a f ai re 
end if 
dig. Dispose 
End Sub 



Sub AvancerO 

Dim av As Double, ok As Object, demarre As Object, champProgres As Object 

demarre = dlg.getControl ("DemarrerBouton") 
demarre. Enable = False ' desactiver le bouton 
champProgres = dl g . getControl ("ProgressBarl") 
' recuperer la valeur initiale d'avancement 
av = champProgres .Val ue 
Do While av < 100.0 

wait 100 ' attend re 100 mi 1 1 i secondes 

av = av + 2 

champProgres. Value = av ' la barre s'allonge... 
Loop 

ok = dlg.getControl ("OKbouton") 
ok. Enable = True ' activer le bouton 
MsgBox("Travai 1 termine") 
End Sub 

La variable dig est declaree comme Private car elle est utilisee par les deux routines 
du module. 

Nous pourrions initialiser la valeur de la barre de progression avec la propriete Val ue, 
qui est du type Doubl e. Ici c'est inutile car deja fait avec l'EDI. Lappel de la fonction 
Execute va tester si le dialogue se termine normalement ou s'il a ete annule. Dans ce 
cas, il est necessaire de defaire ce qui a ete fait. 
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La routine Avancer est lancee par l'evenement Lors du declenchement du bouton 
Lancer ; cette affectation se fait avec l'EDI, comme decrit plus haut dans la section 
« Premieres notions d'evenement ». Nous simulons un travail qui prend un certain 
temps avec l'instruction wai t et une augmentation progressive de la valeur du champ 
de progression. A la fin de la boucle, le travail est termine. Le bouton OK du dialogue 
est alors active afin que l'utilisateur puisse eventuellement le declencher. Un message 
visualise cet instant. 

II est important de comprendre qua tout moment pendant l'execution de la boucle, 
l'utilisateur peut declencher le bouton Annuler. Alors, la boite de dialogue disparait, 
mais la routine Avancer continue aveuglement. Quand elle est terminee, l'execution 
du programme reprend a l'instruction if de la routine BarreProgression. De la 
meme maniere, l'utilisateur pourrait actionner plusieurs fois le bouton Lancer, ce qui 
relancerait la routine Avancer avec des consequences genantes. Pour les eviter, nous 
desactivons ce bouton en debut de routine. 

Methode alternative 

Au chapitre 14 nous verrons un meilleur moyen d'afficher la progression d'un travail, en utilisant la barre 
d'etat de la fenetre. 



Principes a connaitre pour des dialogues elabores 

Maintenant que vous connaissez les controles de dialogue, voici quelques notions 
tres utiles pour la conception de dialogues. Elles nous serviront dans les exemples qui 
vont suivre. 

Le contrdle et son modele 

Ce que nous appelons couramment « controle » est, du point de vue technique, la vue 
du controle. En effet, OpenOffice.org distingue la vue du controle et son modele. 
Grosso modo, les proprietes du modele gerent tout ce qui est modifiable par le pan- 
neau Proprietes dans l'EDI, alors que les aspects lies a l'execution sont traites directe- 
ment par la vue du controle. Le panneau de dialogue lui-meme presente ce double 
aspect, vue et modele. 

Pour aller plus loin 

Le chapitre Programming Dialogs and Dialog Controls du Developer's Guide decrit techniquement les 
concepts d'implementation des dialogues. 
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L'objet controle (ou dialogue) et son objet modele sont lies. Une modification de l'un 
peut declencher une mise a jour de l'autre et reciproquement. De plus, il arrive que la 
meme information soit accessible via le controle et via son modele, avec des noms de 
methode ou propriete identiques ou differents... 

II existe deux manieres d'acceder au modele d'un controle : soit a partir du controle 
(sa vue), soit a partir du modele du dialogue. On suppose ici que la variable dig 
represents l'objet dialogue. 

dim k As Object, mk As Object, mk2 As Object, md As Object 

k = dig .getControl ("TextFieldl") ' la vue du controle TextFieldl 

mk = k. Model ' le modele du controle TextFieldl 

md = dig. Model ' le modele du panneau de dialogue 

' deuxieme maniere d'acceder au modele du controle TextFieldl 

mk2 = md.getByName("TextFieldl") 

Nous utiliserons souvent la premiere maniere, sans utiliser la variable 
intermediate mk pour acceder a une propriete ou methode du modele. Remarquez 
que le nom d'un controle n' existe que sur son modele. 

I k = dig. getControl ("TextFieldl") 

I k. Model .Readonly = True 

I MsgBox("Contr61e : " & k . Model . Name) 



Relations entre contrdles et dialogue 

Depuis un objet controle, on accede au dialogue qui le gere avec la propriete Context. 
Ceci est tres utile dans un codage traitant un evenement sur un dialogue : 

dig = leControle. Context 

Depuis un dialogue, nous savons que la methode getControl permet d'obtenir un 
controle dont on connait le nom. II est aussi possible de balayer tous les controles 
appartenant au dialogue grace a sa pseudo-propriete Control s qui renvoie un tableau 
d'objets controles : 

Dim dig As Object, k As Object, lesCtrls() as object 
lesCtrls = dig. Controls 
for each k in lesCtrlsO 

MsgBox("Contr61e : " & k . Model . Name) 
next 

De meme, depuis le modele du dialogue, la pseudo-propriete Cont rol Model s renvoie 
un tableau des modeles de controles. 
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Les autres proprietes de contrdle et de dialogue 

Chaque modele de controle et dialogue possede une propriete Tag (dans l'EDI, cette 
propriete est appelee Complement conformation). Elle est du type Stri ng, et n'a aucun 
utilite particuliere ! En effet, elle est a votre disposition pour memoriser toute infor- 
mation dont vous auriez besoin (on peut mettre beaucoup d'informations dans une 
chaine de caracteres). Nous en verrons un usage bientot. 

Les proprietes du dialogue et de chaque type de controle sont nombreuses, tant au 
niveau de la vue qu'au niveau du modele. L'outil Xray (voir l'annexe A) les affichera 
facilement. Vous trouverez dans le Zip telechargeable, dans le repertoire consacre a 
ce chapitre, le fichier PropsDialogue.ods qui contient une liste synthetique des pro- 
prietes de chacun des controles. Notez que certaines proprietes ne sont pas docu- 
mentees ou s'averent inefficaces. 

Remettre a « vide » un champ numerique 

Comment ne mettre aucune valeur dans le champ d'un controle numerique ? Avec 
l'EDI, c'est possible en supprimant toute valeur. Dynamiquement (sur un evenement), 
il suffit de mettre une chaine de caracteres nulle dans la propriete Text du controle. 

champ Ponds. Text = "" 

Une autre methode, qui fonctionne aussi sur d'autres controles, est de reinitialiser la 
propriete Value dans le modele du controle : 

I champPoi ds. Model . PropertyToDef aul t = "Value" 



Attention 

La Val ueMi n ne sera pas prise en compte si I'utilisateur ne remplit pas le champ. Dans ce cas la valeur 
recuperee est zero. 



Gerer dynamiquement les controles de dialogue 

Bien qu'il soit preferable de definir a partir de l'EDI les parametres de chacun des 
elements d'une boite de dialogue, vous aurez parfois l'information necessaire seule- 
ment au moment de l'execution de la macro. De plus, il peut etre necessaire d'effec- 
tuer un traitement avant de fermer le dialogue. Notre premier cas utilise plusieurs 
notions fondamentales pour aboutir a une solution reutilisable. 
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Declencher une routine dans un dialogue 

L'apparence du panneau de dialogue de la figure 11-31 est celle de l'EDI. Nous 
avons mis un controle Zone de texte multiligne, en lecture seule, et avec des ascen- 
seurs horizontaux et verticaux ; un deuxieme controle Zone de texte, un bouton 
Annuler, et un bouton OK qui est en fait un bouton de type « par defaut ». 

Panneau de dialogue « brut » 



Le controle multiligne sera rempli par programme avant d'afficher le dialogue. L'uti- 
lisateur devra en recopier un extrait dans la deuxieme zone de texte. Le dialogue se 
fermera : 

• s'il est annule ; 

• ou en actionnant le bouton OK et si le texte recopie existe avec une longueur suffi- 



Si le texte recopie est incorrect, le bouton OK ne ferme pas le dialogue et un message 
d'erreur est affiche. Void le code complet, les explications suivent. 

rem Codell-04.odt bibli : ModifDyn Modulel 
Option Explicit 

Sub UnBoutonActif () 

Dim dig As Object, texteRef As Object, choix As Object 

dig = CreerDi al ogue("Modi fDyn" , "Dialogl") 
texteRef = dl g . getControl ("TextFi el dl") 
texteRef .Text = ThisComponent . Text. String 
dig. execute 

if dig. Model .Tag = "OK" then 

choix = dig. getControl ("TextFi el d2") 
MsgBox("Extrait choisi : " & chr(10) & choix. Text) 





sante. 
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else 

MsgBox("Dialogue annule") 
end if 
dig. dispose 
End Sub 



' execute sur dec! enchement du bouton OK 
Sub val idationExtrait(evt As Object) 

Dim dig As Object, texteRef As Object, choix As Object 
Dim extrait As String 

dig = evt .Source. Context 

texteRef = dl g . getControl ("TextFi el dl") 
choix = dig. getControl ("TextField2") 
extrait = Trim (choix. Text) 
if Len(extrait) < 5 then 

MsgBox("Cet extrait est trop court : " & chr(10) & extrait, 16) 
elseif InStr(l, texteRef .Text , extrait, 0) = 0 then 

MsgBox("Cet extrait n'est pas dans le texte", 16) 
el se 

dlg.endExecute 

dig. Model .Tag = "OK" 
end if 
End Sub 

La routine UnBoutonActif cree le dialogue, puis remplit le controle Zone de texte 
avec le texte du document. Remarquez que, par programme, nous pouvons ecrire 
dans un controle en lecture seule pour l'utilisateur. Le dialogue est affiche par la 
methode execute, mais ici nous ne testons pas son resultat. En effet, nous lisons le 
contenu de la propriete Tag du modele de dialogue pour distinguer le cas d'annula- 
tion. A la creation du dialogue, elle contient une chaine vide. Comment cela fonc- 
tionne-t-il ? Grace a une routine executee sur l'evenement de declenchement du 
bouton OK. Dans l'EDI vous verrez que l'evenement Lors du declenchement de ce 
bouton a ete affecte a la routine validation Ext rait. 

Avant d'examiner la routine d'evenement, soulignons le point suivant : l'affectation 
d'un evenement a un bouton n'est efficace que s'il a le type Par defaut. Si le bouton 
etait de type OK ou Annuler ou Aide, la routine ne serait pas executee. Ceci complique 
un peu le codage. 

Une routine d'evenement recoit dans un parametre (ici la variable evt) un objet spe- 
cifique de l'evenement. Le contenu de cet objet depend du type d'evenement, mais il 
possede toujours une propriete Source qui donne 1' objet a l'origine de l'evenement. 
Cet objet est ici notre controle Bouton. Comme nous l'avons vu plus haut, depuis ce 
controle on peut obtenir son dialogue par la propriete Context. Ceci nous evite de 
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declarer commune (Pri vate ou Publ i c) la variable contenant le dialogue. A partir du 
dialogue, nous retrouvons ses controles. Pour clarifier, nous avons repris les memes 
noms de variables que dans la routine principale, mais ceci n'est pas obligatoire. 

La routine d'evenement verifie done, d'une part que le texte choisi est suffisamment 
long, et d'autre part qu'il existe bien dans le texte propose. En cas d'erreur, un mes- 
sage est affiche et la routine se termine : le dialogue reste. Si le texte choisi est accep- 
table, on l'indique dans la propriete Tag du modele de controle, et on termine le dia- 
logue en employant la methode endExecute de celui-ci. Cette methode a pour 
consequence de fermer le dialogue quand la routine d'evenement sera terminee (et 
seulement a ce moment-la). La methode execute du dialogue retourne alors la 
meme valeur que pour une annulation, ce qui oblige a distinguer les deux cas. Lusage 
de la propriete Tag nous evite de declarer une variable commune aux deux routines. 
Dans un cas reel, le dialogue pourrait comporter de nombreux autres controles, et la 
routine de validation pourrait verifier la coherence entre certains d'entre eux. 

Gestionnaire d'evenements commun a plusieurs controles 

Certains dialogues comportent plusieurs controles dont le traitement doit etre simi- 
laire. II est tout a fait possible d'affecter le meme gestionnaire d'evenements a des 
evenements de plusieurs controles. Mais alors comment determiner le controle ayant 
declenche l'evenement ? En recuperant sur le controle un element qui lui est speci- 
fique, par exemple son nom, a savoir la propriete Name du modele. Mais, encore une 
fois, la propriete Tag nous offre une solution plus elegante. La figure 11-32 presente 
un dialogue dans lequel on affiche dans un controle Etiquette un texte de salutation. 
Chaque bouton de gauche affiche le texte dans une langue differente, grace a une 
routine evenementielle commune. 

rem Codell-04.odt bibli : ModifDyn Module2 
Option Explicit 

Sub GererPlusieursControlesO 
Dim dig As Object 

dig = CreerDialogue("ModifDyn" , "Dialog2") 
dl g . execute 
dig. dispose 
End Sub 

1 declenche par les boutons de langue 
Sub boutonsLangue(evt As Object) 

Dim btnEvt As Object, aff As Object, dig As Object 
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btnEvt = evt. Source 

dig = btnEvt. Context 

aff = dlg.getControl ("Af fi chage") 

aff.Text = btnEvt. Model .Tag 

End Sub 



Figure 11-32 

Salutation intemationale 




II suffit, dans l'EDI, d'affecter a la propriete Complement d'information de chaque 
bouton le texte correspondant. La routine boutonsLangue recupere son contenu et 
l'affecte a la propriete Text du controle Etiquette. Ce principe n'est absolument pas 
limite a une chaine de caracteres : on pourrait mettre un nombre (qui serait converti en 
caracteres) et le recuperer par une conversion inverse dans une variable Long ou Doubl e. 



ASTUCE Creer de nombreux contrdles similaires 

Vous avez peut-etre remarque que si on selectionne plusieurs controles, meme de type identique, il n'est 
pas possible de leur affecter une routine d'evenement commune. Une meilleure methode de travail con- 
sists a creer un premier controle, remplir ses valeurs, y compris I'affectation d'une routine a un evene- 
ment. Ce controle etant selectionne, copiez-le dans le Presse-Papier, puis deselectionnez-le. Collez depuis 
le Presse-Papier, vous obtenez un nouveau controle que vous deplacerez a sa position finale. Deselection- 
nez, recommencez le collage pour le suivant. Chacun a ainsi la meme routine d'evenement. Personnali- 
sez ensuite chaque controle (son nom et son libel le, par exemple). 



Modifier le contenu d'une zone de liste 

Les differentes valeurs de la liste de choix ne sont pas necessairement remplies depuis 
l'EDI. Lexemple qui suit cree une liste de choix, l'affiche dans un dialogue, et sup- 
prime ou ajoute des elements dans la liste grace a des routines declenchees par des 
boutons. II utilise des proprietes et methodes de l'objet Zone de liste, parmi celles 
citees au tableau 11-2. Les arguments de methodes sont explicites au tableau 11-3. 

rem Codell-04 . odt bibli : ModifDyn Module3 
Option Explicit 
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I Sub Choi xDynami que () 
Dim dig As Object, "listeChoix As Variant, k As Object 
"HsteChoix = ArrayC'Hector" , "Charles Edouard", "Annie", "Josephine", 
"Raoul", "Mireille", "Norbert", "Pauline", "Xavier") 

dig = CreerDialogue("ModifDyn" , "Dialog3") 

k = dlg.getControl ("ListBoxl") 

k. Model .StringltemLi st = listeChoixO 

k.selectItemPos(0, True) 

dig. execute 

dl g . di spose 

End Sub 



Sub supprimerElement(evt As Object) ' le bouton Supprimer est actionne 

Dim dig As Object, k As Object, position As Long 

dig = evt. Source. Context 1 recuperer le dialogue 

k = dlg.getControl ("ListBoxl") 

position = k.SelectedltemPos 

k. removeltems(posi tion , 1) 

if position >= k.ItemCount then position = k.ItemCount -1 
if position >= 0 then k.selectltemPos (position, True) 
End Sub 



Sub ajouterElement(evt As Object) ' le bouton Ajouter est actionne 

Dim dig As Object, kl As Object, k2 As Object, position As Long 

dig = evt. Source. Context ' recuperer le dialogue 

kl = dlg.getControl ("ListBoxl") 

k2 = dlg.getControl ("TextFi el dl") 

position = kl.SelectedltemPos 

kl.addltem(k2 .Text, position) 

kl. selectltem(k2 .Text, True) 

End Sub 



Tableau 11-2 Gestion d'une zone liste 



Methode / Propriete 


Signification 


Resultat 


Model . Stri ngltemLi st 


Liste des elements, modifiable. 


□ String 


Items 


Liste des elements, en lecture seule. 


□ String 


ItemCount 


Nombre d'elements de la liste, en lecture seule. 


Integer 


SelectedltemPos 


Rang de I'element selectionne, a partir de zero. 


Integer 


Sel ectedltem 


Element selectionne. 


Stri ng 


Sel ectedltemsPos 


Liste des rangs des elements selectionnes. 


[] Integer 


Selectedltems 


Liste des elements selectionnes. 


□ String 


addltem(elem, rang) 


Ajoute un element. 


aucun 
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Tableau 11-2 Gestion d'une zone liste (suite) 



addltems([]elem, rang) Ajoute plusieurs elements a partir du rang indique. aucun 


removeItems(rang , nombre) 


Supprime un nombre d'elements a partir du rang 
indique. 


aucun 


selectltem(elem, sel) 


Selectionne ou deselectionne I'element indique. 


aucun 


selectItemPos(rang, sel) 


Selectionne ou deselectionne I'element dont le 
rang est indique. 


aucun 


selectItemsPos([] rang, sel) 


Selectionne ou deselectionne les elements dont les 
rangs sont indiques. 


aucun 



Tableau 11-3 Termes employes 



el em 


Stri ng 


Libelle d'un element de choix. 


rang 


Integer 


Position d'un element de choix, compte a partir de zero. 


sel 


Boolean 


True pour selectionner I'element. 
Fal se pour deselectionner I'element. 


[] 


Array 


Tableau de valeurs, indexe a partir de zero. Le type de chaque valeur est indique a 
droite, exemple [] String. 



Notre dialogue emploie une zone de liste a choix unique. Le principe serait similaire 
pour un choix multiple. L'ensemble des choix possibles se presente sous la forme d'un 
tableau de chaines de caracteres. Nous l'avons rempli avec la fonction Basic Array 
pour simplifier, mais on aurait pu declarer une variable tableau et remplir ensuite 
chaque element. Ce tableau est transfere dans la Zone de liste en l'affectant a la pro- 
priete Stri ngltemLi st de son modele. 

Bien que ce soit peu courant, il est tout a fait possible d'afficher une liste de choix 
sans aucun element selectionne. Ici, nous selectionnons un des elements de la liste 
avec la methode sel ectltemPos. Comme notre liste est a choix unique, une action de 
selection conduit a deselectionner un eventuel autre element selectionne. Dans le cas 
d'une zone de liste ou plusieurs choix simultanes sont possibles, l'indicateur booleen 
sel offre toutes facilites de selection/deselection. Le dialogue est affiche, les deux 
routines qui suivent sont declenchees chacune par un bouton. 

La routine supprimerElement elimine de la liste de choix I'element actuellement 
selectionne, c'est-a-dire affiche sur cette Zone de liste deroulante. II est ensuite 
necessaire de selectionner un autre element pour que la Zone de liste affiche quelque 
chose. Le codage s'assure que la nouvelle position selectionnee reste dans la gamme 
des valeurs acceptables. 
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La routine ajouterElement insere le texte du controle Zone de texte dans la liste de 
choix a la position actuellement affichee, en repoussant cet element de choix et les 
suivants. Si on voulait gerer une liste ordonnee, il faudrait developper un petit algo- 
rithme pour determiner la position adequate dans la liste. Nous avons utilise la 
methode addltem, parfaite pour un seul element. Lors d'ajouts en nombre d'elements 
a une liste deroulante, preferez i'utiiisation de la methode addltems, quitte a passer 
par un tableau intermediate. Les appels d'insertion d'elements sont couteux et 
inserer les elements un par un avec la methode addltem risque de degrader les perfor- 
mances de votre macro jusqu'a la rendre inutilisable. 

Modifier dynamiquement les selections multiples 

Lexemple qui suit comporte une zone de liste a choix multiples. Nous ne nous occu- 
perons pas du resultat du dialogue, ce n'est pas notre but. En actionnant des boutons, 
nous allons effacer ou changer les selections dans le dialogue. Revoyez le 
tableau 11-2 et faites tres attention aux noms des methodes et proprietes employees. 

rem Codell-04 . odt bibli : ModifDyn Module5 
Option Explicit 

Sub Modi f i e rSel ecti onMul ti pi e () 

Dim dig As Object, listeChoix As Variant, k As Object 

dig = CreerDialogue("ModifDyn" , "Dialog5") 
k = dlg.getControl ("ListBoxl") 
dig. execute 
dig. dispose 
End Sub 

' routine declenchee par le bouton "Supprimer toute selection" 

Sub effacerSelections(evt As Object) 

Dim dig As Object, kChoix As Object 

dig = evt. Source. Context 

kChoix = dlg.getControl ("Choix Couleurs") 

if UBound(kChoix.SelectedltemsPos) < 0 then 
MsgBox("Aucun element n'est sel ecti onne") 
el se 

' Suppression de tous les elements selectionnes 
kChoi x . sel ectltemsPos (kChoi x . Sel ectedltemsPos , Fal se) 

end i f 

End Sub 

' routine declenchee par le bouton "Sel ecti onner plusieurs valeurs" 
Sub imposerSelections(evt As Object) 
Dim dig As Object, kChoix As Object 
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dig = evt. Source. Context 
kChoix = dlg.getControl ("Choix Couleurs") 
' Selection des elements 2, 7, 8 
kChoix.selectItemsPos(Array(7,2 ,8) , True) 
End Sub 

Le bouton Supprimer toute selection declenche une routine qui recupere le controle 
Zone de liste. Nous savons deja que la propriete SelectedltemsPos renvoie un 
tableau des rangs correspondant aux elements selectionnes. Nous mettons en premier 
argument de la methode selectltemsPos justement le tableau des positions selec- 
tionnees, et en deuxieme argument la valeur False. Ainsi, tous les elements selec- 
tionnes seront deselectionnes. 

Le bouton Selectionner plusieurs valeurs declenche une autre routine, qui utilise la 
methode selectltemsPos pour selectionner un ou plusieurs elements. Les positions 
a selectionner sont transmises dans un tableau indexe a partir de zero. Nous avons 
utilise la fonction Basic Array pour creer ce tableau. Le deuxieme argument prend la 
valeur True afin de selectionner les elements. Vous constaterez que cette routine ne 
fait qu'ajouter des selections. Pour imposer la totalite du choix, on doit supprimer 
toute selection puis ajouter celles que Ton souhaite. 



Modifier le contenu d'une zone de liste combinee 

Le controle Zone de liste combinee ne comporte qu'un sous-ensemble des methodes 
et proprietes du controle Zone de liste (voir le tableau 11-4). II ajoute en revanche la 
propriete Text qui contient le texte affiche. 

Tableau 11-4 Gestion d'une zone liste combinee 



Model . Stri ngltemLi st 


Liste des elements, modifiable. 


□ String 


Items 


Liste des elements, en lecture seule. 


□ String 


ItemCount 


Nombre d'elements de la liste, en lecture seule. 


Integer 


addltem(elem, rang) 


Ajoute un element. 


aucun 


addltems([]elem, rang) 


Ajoute plusieurs elements a partir du rang indique. 


aucun 


removeItems(rang , nombre) 


Supprime un nombre d'elements a partir du rang indique. 


aucun 


Text 


Valeur affichee. 


String 



Nous allons creer une liste de choix et permettre l'ajout et la suppression d'element. 

rem Codell-04 . odt bibli : ModifDyn Module4 
Option Explicit 
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I Sub ZoneCombi neeDynamique() 
Dim dig As Object, "listeChoix As Variant, k As Object 
"listeChoix = ArrayC'Hector" , "Charles Edouard", "Annie", "Josephine", 
"Raoul", "Mireille", "Norbert", "Pauline", "Xavier") 

dig = CreerDi al ogue("Modi fDyn" , "Dialog4") 

k = dlg.getControl ("ComboBoxl") 

k. Model .StringltemLi st = listeChoixO 

k.Text = k. Items (2) 

dig. execute 

dl g . di spose 

End Sub 



Sub supprimerElement(evt As Object) ' le bouton Supprimer est actionne 
Dim dig As Object, k As Object 

Dim position As Long, element As String, liste() As String 

dig = evt. Source. Context 

k = dlg.getControl ("ComboBoxl") 

element = k.Text 

liste() = k. Items 

position = k.ItemCount -1 

Do While position >= 0 ' retrouver la position de l'element 

if liste (position) = element then Exit Do 

position = position -1 
Loop 

if position >= 0 then ' L'element existe bien dans la liste 
k.removeltems (position, 1) 

if k.ItemCount > 0 then k.Text = k. Items (0) else k.Text = "" 
end if 
End Sub 



Sub ajouterElement(evt As Object) ' le bouton Ajouter est actionne 
Dim dig As Object, k As Object 

Dim position As Long, element As String, liste() As String 

dig = evt. Source. Context 

k = dlg.getControl ("ComboBoxl") 

element = k.Text 

liste() = k. Items 

position = k.ItemCount -1 

Do While position >= 0 ' retrouver la position de l'element 

if 1 i ste(posi ti on) = element then Exit Do 

position = position -1 
Loop 

if position < 0 then k.addltem( k.Text, 0) ' ajout en tete de liste 
End Sub 
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La creation de la liste de choix est identique a l'exemple precedent. L'equivalent de la 
selection d'un element revient a remplir la propriete Text avec le contenu d'un des 
elements ; mais on pourrait mettre un texte quelconque. 

II n'existe pas de methode permettant de supprimer directement l'element dont le texte 
est indique par l'utilisateur. Nous devons faire une boucle pour rechercher la position de 
cet element. L'utilisation des variables intermediaires 1 i ste et el ement accelere un peu 
la recherche dans une longue liste. Si l'element est retrouve, sa position est positive ou 
nulle et nous utilisons la methode removeltems. La valeur affichee doit etre changee ; 
nous avons choisi d'afficher le premier element de la liste, s'il en reste un. 

Lajout d'un element dans la liste ne pose pas de probleme particulier. Apres avoir verifie 
qu'il n'existe pas deja, nous le mettons en tete de liste et gardons sa valeur pour l'affichage. 



Les principaux evenements 

Dans l'EDI, l'onglet Evenement de la page de proprietes permet de lister la plupart des 
evenements que peut produire un dialogue ou un controle, et d'y affecter une routine. 
Sur un meme controle, vous pouvez done affecter des traitements a plusieurs des eve- 
nements disponibles. Vous risquez alors de declencher plusieurs evenements pour la 
meme action de l'utilisateur, et done des appels successifs de vos gestionnaires d'evene- 
ments. Les interactions logicielles entre ces gestionnaires peuvent etre tres difficiles a 
maitriser. Dans la mesure du possible, n'utilisez qu'un seul evenement sur un controle. 

Avec les evenements, vous abordez le domaine du temps reel, qui peut provoquer des 
comportements aleatoires : 

• Un utilisateur rapide peut declencher une deuxieme fois un evenement pendant le 
temps de traitement du premier. 

• Une routine d'evenement peut etre interrompue par une deuxieme routine 
declenchee par un autre evenement, qui modifie une donnee commune. 

• La simple ecriture d'une donnee dans un controle peut declencher un evenement ! 

Ecrivez des gestionnaires simples et rapides, ne multipliez pas les traitements d'eve- 
nements et eventuellement bloquez l'interface utilisateur pendant le traitement (voir 
chapitre 14). 

Nous allons passer en revue les evenements les plus courants. Largument transmis a 
un sous-programme de gestion d'evenement, la variable evt dans nos exemples, est 
une donnee structuree representant l'evenement. La composition de cette structure 
depend du type d'evenement survenu. Seul l'element Source, deja vu, existe pour 
tous les evenements. 
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Pour aller plus loin 

La description des differentes structures d'evenement se trouve dans la documentation de I'API, a la 
page decrivant le module com . sun . star . awt. A partir de la section Struct de cette page, suivez les 
liens concernant ActionEvent, FocusEvent, KeyEvent, MouseEvent, etc. 



Lors du declenchement 

Cet evenement apparait sur plusieurs types de controles. La variable d'evenement 
comporte la propriete ActionCommand, de type String. Elle contient la valeur que le 
programmeur a eventuellement donnee a la propriete ActionCommand du controle. 

• Bouton : il a ete declenche (par clavier ou souris). Seul un bouton de type Par 
defaut peut declencher cet evenement. C'est 1' evenement a utiliser pour une 
action commandee par bouton, il est declenche aussi bien par un clic de souris 
qu'une touche de clavier. 

• Zone de liste, Zone de liste combinee : un choix a ete effectue (par clavier ou souris). 

• Case de choix 1 parmi N : la case est choisie (declenche meme si on clique dessus 
alors quelle etait deja dans l'etat selectionne). 

• Case a cocher : la coche a change d'etat. 

Statut modifie 

Cet evenement apparait sur plusieurs types de controles. La variable d'evenement 
comporte la propriete Selected, de type Long, representative de l'etat du controle 
apres Taction ayant declenche 1' evenement. 

• Zone de liste : Sel ected vaut toujours 1. Levenement est declenche des que l'affi- 
chage a commute sur un autre des elements de la liste. Pour connaitre l'element 
actuellement affiche, recuperez le controle avec la propriete Source. 

• Zone de liste combinee : Selected vaut toujours 1. Levenement ne se declenche 
que si on a selectionne un autre element dans la liste. II ne se declenche pas si on 
a modifie le texte affiche, meme en tapant le texte d'un autre element. 

• Case de choix 1 parmi N : Selected vaut toujours 1. Un seul evenement est 
declenche sur l'ensemble des controles de choix d'un meme groupe. II est declen- 
che sur le controle qui devient coche. 

• Case a cocher : Sel ected vaut 0 si la case n'est pas cochee, 1 si elle est cochee nor- 
malement, 2 si elle est cochee dans l'etat « indetermine ». Chaque changement de 
coche declenche 1' evenement. 
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• Bouton : l'evenement est seulement declenche pour un bouton a bascule (propriete 
Basculer dans l'EDI mise a Out ). La propriete Sel ected vaut 1 si le bouton vient de 
passer en position enfoncee, et vaut 0 si le bouton est passe en position relevee. 

Changement de focus 

II s'agit des evenements Reception de focus et Perte de focus. 

Penchons-nous sur les circonstances d'apparition : toute action qui deplace le focus dans 
le sens correspondant a l'evenement. Cela peut se produire a l'occasion d'un clic ou 
d'un d'appui sur la touche Tab ou sur une touche declenchant un autre bouton, etc. 

L'element FocusFlags, de type Integer, fournit la raison du changement de focus, 
sous la forme de la somme de constantes nominees. Prenons un exemple : 

if evt . FocusFlags = com . sun . star . awt . FocusChangeReason .TAB then 



Chacune de ces constantes, listees au tableau 11-5, est une puissance de deux, ce qui 
permet de detecter sa presence avec un ET logique (operateur and). 

Tableau 11-5 Constantes de FocusFlags 





TAB 


Utilisation de la touche Tabulation. 


CURSOR 


Utilisation d'un touche haut, bas, page precedente, page suivante. 


MNEMONIC 


Utilisation d'une touche de raccourci. 


FORWARD 


Le focus est passe au controle suivant. 


BACKWARD 


Le focus est passe au controle precedent. 


AROUND 


Bouclage sur la liste des controles. 


UNIQUEMNEMONIC 


Le raccourci employe designe un unique controle. 



L'element Temporary, de type Boolean, vaut True si le changement de focus est une 
consequence indirecte d'une autre action (par exemple la fermeture de la fenetre de 
dialogue). 

L'element NextFocus fournit la fenetre qui recoit le focus (en cas de perte de focus). 



Touche du clavier 

II s'agit des evenements Touche enfoncee et Apres avoir lache la touche. 
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L' element KeyCode, de type Integer, identifie la touche appuyee sous la forme d'une 
constante nommee (tableau 11-6), exemple : 

| "if evt. KeyCode = com. sun. star. awt. Key. HOME then 

L'action simultanee d'une touche Maj, Ctrl ou Alt, n'a pas d'influence sur la valeur 
donnee par KeyCode. 

Tableau 11-6 Constantes de KeyCode 



NUMOa NUM9 


1 a 9 (clavier numerique ou principal) 


AaZ 


lettre majuscule ou minuscule 


Fla F26 


Touche de fonction 


DOWN 


Direction bas 


UP 


Direction haut 


LEFT 


Direction gauche 


RIGHT 


Direction droite 


HOME 


Direction coin 


END 


Fin 


PAGEUP 


Page precedente 


PAGEDOWN 


Page suivante 


RETURN 


Entree 


ESCAPE 


Echap 


TAB 


Tabulation 



DELETE 


Suppr 


ADD 


+ 


SUBSTRACT 




MULTIPLY 


* 


DIVIDE 


/ 


POINT 


Point 


COMMA 


Virgule 


LESS 


< 


GREATER 


> 


EQUAL signe = 


INSERT 


Inser 


SPACE 


Espace 


BACKSPACE 


Retour arriere 



L'element KeyChar, de type String, donne : 

• soit le caractere correspondant, en tenant compte de la touche Maj ; 

• soit un pseudo-caractere dont la valeur ASC est inferieure a 32, (exemple Entree 
donne 13) ; 

• soit un pseudo-caractere dont la valeur ASC est zero. 
| if evt. KeyChar = "X" then 

L'element KeyFunc, de type Integer, indique la signification fonctionnelle de la 
touche, quand elle en a une. C'est une constante nommee (voir tableau 11-7), 
exemple : 

| "if evt. KeyFunc = com . sun . star . awt . KeyFuncti on . DONTKNOW then 
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Une touche ordinaire renvoie la valeur DONTKNOW. La touche Ctrl + C renvoie COPY. 
Certains valeurs sont particulieres a certains claviers et systemes. 



Tableau 11-7 Constantes de KeyFunc 



instante 



DONTKNOW 


Aucune 


NEW 


Nouveau 


OPEN 


Ouvrir 


SAVE 


Enregistrer 


SAVEAS 


Enregistrer sous 


PRINT 


Imprimer 


CLOSE 


Fermer 


QUIT 


Quitter 


PROPERTIES 


Proprietes 



CUT 


Couper 


COPY 


Copier 


PASTE 


Coller 


UNDO 


Defaire 


REDO 


Refaire 


REPEAT 


Repeter 


FIND 


Chercher 


FINDBACKWARD 


Chercher en sens inverse 


FRONT 


Avant-plan 



L' element Modifiers, de type Integer, indique si une touche Maj, Ctrl ou Alt est 
pressee. A chacune correspond une constante nommee : 

com. sun. star. awt . KeyModi fi er . MODI ' touche Ctrl 
com. sun. star. awt.KeyModifier.MOD2 ' touche Alt 
com. sun. star. awt. KeyModi fier. SHIFT ' touche Maj 

Les valeurs des constantes etant des puissances de deux, on determine lesquelles sont 
activees avec un ET logique. 



Souris 



Attention 

Certains evenements de souris peuvent se declencher un grand nombre de fois par seconde. 

Lelement KeyModi fiers est disponible, nous l'avons decrit plus haut. Lelement 
Buttons, de type Integer, indique quels boutons de souris sont presses. A chacun 
correspond une constante nommee : 

com. sun . star . awt . MouseButton . LEFT ' bouton gauche 
com. sun. star. awt. MouseButton. RIGHT ' bouton droit 
com . sun . star . awt . MouseButton .MIDDLE ' bouton du milieu 
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Les elements X et Y, de type Long, indiquent la position de la souris, exprimee en 
pixels, la valeur 0 correspondant respectivement au bord gauche et au bord haut de la 
surface du controle. L'element ClickCount, de type Long, compte le nombre de clics 
effectues. Elle est remise automatiquement a zero apres une temporisation de quel- 
ques dixiemes de secondes. Plusieurs clics successifs declencheront autant de fois 
1' evenement Bouton de souris enfonce (par exemple). La valeur ne peut etre modifiee 
par programmation. L'element PopupTri gger, de type Bool ean, indique True si l'eve- 
nement correspond a l'ouverture d'un menu contextuel. 

Texte Modifie 

Cet evenement apparait dans les controles ou l'utilisateur peut modifier un texte ou 
une valeur numerique, et a chaque modification, meme d'un seul caractere. II n'existe 
aucune information transmise avec cet evenement. 



Ajouter des controles par programme 

II est de loin preferable de definir toute la structure d'un dialogue avec l'EDI. Si vous 
ressentez le besoin d'ajouter par programme un nombre variable de boutons ou autres 
controles, etudiez votre probleme sous d'autres angles. II y a probablement une 
meilleure solution en repensant le principe de votre dialogue. 

Pour chaque controle ajoute, il va falloir remplir toutes les proprietes necessaires, et 
pour chaque traitement d'evenement du controle, lui affecter un Listener (ce point est 
explique au chapitre 14). Vous trouverez dans la documentation de l'API a la page 
com. sun. star. awt les services pour chaque type de modele de controle et les inter- 
faces des Listener disponibles. Dans l'exemple suivant, nous ajoutons a un dialogue 
un bouton et une zone de texte. Le declenchement du bouton lancera une routine de 
traitement. 

rem Codell-04.odt bibli : AjoutCtrl Modulel 
option explicit 

Sub MainlO 

Dim dig As Object, km As Object, k As Object, clic As Object 
dig = CreerDialogue("AjoutCtrl", "Dialogl") 

' creer le modele du bouton a inserer 

km = dl g . Model . createlnstance ("com . sun . star . awt . UnoControl ButtonModel ") 

km.PositionX = 10 
km.PositionY = 20 
km. Width = 30 
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km. Height = 15 
km. Name = "unBouton" 
km.Tablndex = 2 
km. Label = "Coucou" 

' inserer le model e du control e dans le model e du dialogue 

dig. Model . insertByName(km . Name , km) 

' affecter une routine au decl enchement du bouton 

clic = CreateUnoListener ("bouton ", "com. sun. star. awt.XActionListener") 
k = dig. getControl ("unBouton") ' recuperer le bouton lui-meme 
k.addActionListener(cl i c) 

' creer le model e du control e Zone de texte a inserer 

km = dig. Model . createInstance("com. sun. star. awt.UnoControlEditModel ") 

km. PositionX = 60 

km.PositionY = 20 

km. Width = 40 

km. Height = 15 

km. Name = "une zone texte" 

km.Tablndex = 3 

km. Text = "xxx" 

km. Align = 1 ' centrer le texte 

' inserer le model e du control e dans le model e du dialogue 
dig. Model .insertByName(km.Name, km) 

dig. execute 
dig. dispose 
End Sub 



Sub bouton actionPerformed(evt As Object) 

MsgBox("Le controle " & evt. Source. Model .Name & " vous salue bien!") 
End Sub 



Sub bouton disposing (evt As Object) 
End Sub 

Le dialogue a ete cree avec l'EDI, il ne comporte qu'un bouton OK et un bouton 
Annuler. Chaque nouveau controle est cree a partir de son modele, au moyen de la 
methode createlnstance du modele du dialogue. L'argument est le nom du service 
supportant le type de controle a creer. Chaque propriete est ensuite initialisee, puis le 
controle est insere dans le modele du dialogue, en precisant son nom. Pour le bouton, 
i'evenement Lors du declenchement de l'EDI est gere par l'interface 
XActionListener. On cree l'objet Listener avec la fonction Basic 
CreateUnoListener, et on l'affecte a la vue du controle bouton avec la methode 
addActionLi stener, specifique de ce gestionnaire d'evenements. 
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L'interface XActionListener expose la methode actionPerformed, qui est executee 
au declenchement du bouton. La routine correspondante doit avoir un nom portant 
le prefixe indique dans CreateUnoListener suivi du nom de la methode invoquee. La 
methode di sposi ng existe pour tout gestionnaire d'evenements, elle doit trouver une 
routine d'un nom correspondant, meme vide. 

On voit ici combien l'EDI simplifie le codage, par rapport a une creation a la volee. 



Gestion du panneau de dialogue 



Position et dimensions d'un dialogue 

Lorigine des coordonnees d'un dialogue est le coin du haut a gauche de la fenetre 
parente. Habituellement, cette fenetre est celle du document ouvert. Par defaut, un 
dialogue apparait centre dans la fenetre parente, ce qui assure une bonne visibilite. 
Dans certaines situations, notamment quand un dialogue affiche un deuxieme dia- 
logue, on peut souhaiter positionner la nouvelle fenetre differemment, par exemple 
decalee par rapport a la fenetre parente. Ceci est realisable en utilisant la methode 
setPosSize du dialogue, que nous allons utiliser dans le dialogue de la figure 11-33. 

rem Codell-04.odt bibli : Dial Dial Modulel 
Option Explicit 

Sub positionnerDialogueO 

Dim dig As Object, X As Long, Y As Long, p As Object 
dig = CreerDialogue("DialDial " , "Dialogl") 

Do While dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK 
X = dig. getControl ("Position X"). Value 
Y = dig. getControl ("Position Y"). Value 
dlg.setPosSize(X, Y, 0, 0, com. sun. star. awt.PosSize.POS) 

Loop 

dig. dispose 
End Sub 

' routine executee en actionnant le bouton "Mettre a jour" 

Sub donnerCoordonneesActuelles(evt As Object) 

Dim p As Object, dig As Object, k As Object 

dig = evt. Source. Context 

p = dig. Peer. PosSize 

k = dig. getControl ("Actu X") 

k.Text = p.X 

k = dig. getControl ("Actu Y") 



Les bottes de dialogue 

Chapitre 1 1 



k.Text = p.Y 

k = dig. getControl ("Largeur") 

k.Text = p. Width 

k = cng.getControl ("Hauteur") 

k.Text = p. Height 

End Sub 



Figure 11-33 

Dialogue positionnable 




Le panneau de dialogue permet d'afficher sur sa gauche la position actuelle du dia- 
logue. Cette information ne peut etre obtenue qu'une fois le dialogue affiche, c'est 
pourquoi il faut actionner le bouton Mise a jour. La routine 
donnerCoordonneesActuel 1 es utilise l'objet Peer du dialogue pour obtenir la pro- 
priete PosSize. Cette propriete donne une structure Rectangle decrite au tableau 11-8 
(les valeurs sont exprimees en pixels). Les valeurs de largeur et hauteur sont un peu plus 
petites que les dimensions reelles du dialogue, car le dialogue visible comporte en plus 
une marge geree par le systeme d'exploitation, notamment le titre de la fenetre. 



Tableau 11-8 Structure Rectangle 





X 


Long 


Position horizontale du coin haut-gauche. 


Y 


Long 


Position verticale du coin haut-gauche. 


Width 


Long 


Largeur. 


Height 


Long 


Hauteur. 



Sur la droite du panneau, nous avons deux champs numeriques et un bouton pour 
changer les coordonnees X et Y du coin haut-gauche du panneau de dialogue. En 
actionnant le bouton Changer la position, les nouvelles coordonnees X et Y servent 
d'argument (de type Long) pour la methode setPosSize du dialogue. Les 
arguments 3 et 4 correspondent a une nouvelle valeur de largeur et hauteur, nous ne 
les utilisons pas. Le cinquieme argument est une constante nommee precisant ce qui 
est a realiser. Comme ici nous realisons un repositionnement, seuls les arguments X 
et Y sont done pris en compte. Le dialogue est reaffiche, jusqu'a ce qu'il soit ferme 
par l'utilisateur (par le bouton Quitter ou la touche Echap). 
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Essayez diverses valeurs, vous remarquerez ceci : 

• II est possible d'utiliser des valeurs negatives. 

• Les coordonnees nouvelles ne sont pas acceptees si le dialogue est amene a dispa- 
raitre de l'ecran ; soit la position reste inchangee, soit le dialogue est recentre. 

Dialogues emboites 

Notre exemple va montrer comment emboiter des dialogues et les positionner. II est 
preferable d'ouvrir le document du Zip telechargeable afin de profiter des dialogues 
deja configures. 

rem Codell-04.odt bibli : Dial Dial Module2 
Option Explicit 

Sub DialoguesImbriques() 
Dim dig As Object 

dig = DialogueC'DialDial", "Dlgl") 
dig. execute 
dig. dispose 
End Sub 



' declenche par les boutons Lancer Dialogue n 

Sub LancerDi al ogue(evt As Object) 

Dim dig As Object, nomDialog As String 

nomDialog = evt. Source. Model .Tag 

dig = CreerDialogue("DialDial " , nomDialog) 

dig. execute 

dig. dispose 

End Sub 



1 declenche par le bouton Lancer et centrer Dialogue 2 
Sub LancerDi al ogueCentre(evt As Object) 

Dim dig As Object, dlgParent As Object, nomDialog As String 

nomDialog = evt. Source. Model .Tag 

dig = CreerDialogue("DialDial " , nomDialog) 

dlgParent = evt. Source. Context 

CenterDialog(dlg, dlgParent) 

dig. execute 

dig. dispose 

End Sub 



Sub CenterDialog(nouvDial As Object, optional parentDial As Object) 
Dim parentSize As Object, XPos As Long, YPos As Long 
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' les tallies et positions sont exprimees en pixels 

if isMissing(parentDial) then 

if IsNull (StarDesktop.CurrentFrame) then exit sub 
parentSize = StarDesktop . CurrentFrame . ComponentWi ndow. Si ze 

el se 

parentSize = parentDi al . Si ze 
end i f 

XPos = (parentSize. Width/2) - (nouvDi al . Si ze .Wi dth/2) 

YPos = (parentSize. Height/2) - (nouvDi al . Si ze . Hei ght/2) 

nouvDial . setPosSi ze(XPos , YPos, 0, 0, com . sun . star . awt . PosSi ze . POS) 

End Sub 

Le premier dialogue est affiche comme d'habitude. II comporte deux boutons pour 
afficher le dialogue Dlg2. Leur propriete Tag (Complement d'information) contient le 
nom du dialogue a appeler. Normalement, OpenOffice va centrer le dialogue enfant 
dans la fenetre parente (ici la fenetre de Dlgl), comme sur la figure 11-34. Mais si le 
dialogue enfant est de plus grandes dimensions (largeur et hauteur) que la fenetre 
parente, OpenOffice utilisera les coordonnees relatives du dialogue dans sa fenetre 
EDI. Le deuxieme bouton appelle une routine CenterDialog pour forcer le centrage 
du dialogue enfant dans ce cas. Essayez diverses tailles du dialogue Dlg2. 



Les dialogues 2 et 3 ne comportent qu'un seul bouton, pour simplifier. Nous arretons 
la demonstration au niveau 4. Vous aurez remarque que les variables de dialogue sont 
toutes locales, memorisees dans la pile des appels des routines. 



Les dialogues OpenOffice.org ne disposent pas de controle a onglets. La methode 
du Step est ce qui s'en rapproche le plus. Ce mecanisme a ete invente pour les dialo- 
gues comme ceux des Assistants, ou l'utilisateur est guide pas a pas dans un processus 
a plusieurs etapes. II utilise la propriete Step, appelee Page dans le panneau Proprietes 



Figure 11-34 

Quatre dialogues centres 




Dialogues a pages multiples 
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de l'EDI. Cette propriete est disponible dans le panneau de dialogue lui-meme et 
dans chacun des controles. On y accede par programmation comme Model . Step, qui 
est du type Long. Le principe consiste a rendre visible ou non chaque controle selon 
la valeur de son Step : 

• Si le Step du controle vaut zero, le controle est visible en permanence. 

• Si le Step du panneau vaut zero, tous les controles sont visibles. 

• Si le Step du panneau vaut N, seuls les controles dont le Step vaut N sont visibles, 
ainsi que ceux dont le Step vaut zero. 

• Par defaut, tous les Step sont a zero et tous les controles sont visibles. 

• Dans l'EDI, quand on depose un nouveau controle sur le dialogue, le Step de ce 
controle est initialise a la valeur actuelle du Step du dialogue. 



Attention 

Puisque I'affichage des controles dans l'EDI depend des valeurs de Step, vous ne verrez sans doute pas 
tous les controles si le Step du dialogue est different de zero. 

La conception d'un tel dialogue peut amener a definir plusieurs controles (par exemple des boutons) 
superposes, car normalement un seul est visible a la fois. Dans ce cas, vous devrez changer dans l'EDI la 
valeur de Step du panneau pour acceder a un controle cache. 



En general, on definit un ou plusieurs controles (boutons, par exemple) ayant un 
Step nul afin qu'ils soient toujours visibles a 1' execution. Quand l'utilisateur active un 
de ces controles, un traitement s'effectue, puis le Step du panneau est modifie. La 
conception et la mise au point d'un dialogue a pages multiples peut etre assez com- 
plexe. Le document Codell-05 .odt du Zip telechargeable contient dans la biblio- 
theque Steps une ebauche d'un tel dialogue. 

Les dialogues multilingues 

Linterface utilisateur d'OpenOffice.org est disponible en diverses langues. Ainsi, 
dans une entreprise multinationale, les employes jouissent sur chaque site d'une 
interface comprehensible. 

Mieux encore, sur une version localisee d'OpenOffice.org, il est possible d'ajouter des 
langpach (paquets linguistiques) contenant chacun tous les textes d'interface dans une 
langue (voir dans 1' annexe C la section concernant les sites de telechargement d'Open- 
Office.org). Une fois installes, depuis le menu Outils>Options>Parametres linguisti- 
ques>Langues il suffit de choisir dans Interface utilisateur une des langues disponibles et 
de fermer et de relancer OpenOffice.org : l'interface s'exprime dans une autre langue ! 
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Les dialogues fournis prets a l'emploi par l'API, comme un MsgBox, utilisent la 
langue de l'interface utilisateur pour les textes comme OK, Annuler, Ignorer, etc. Vous 
pouvez creer vos dialogues en version multilingue. 

Definir un dialogue multilingue 

Sur votre systeme de developpement, vous devez installer toutes les langues que vos 
dialogues pourront gerer, afin de pouvoir les tester en condition reelles. Prenons 
comme exemple un dialogue avec une Zone de texte et une Zone de liste combinee 
(figure 11-35). 

Figure 11-35 

Un dialogue simple 



Dans le menu Afficher de l'EDI, affichez la barre d'outils Langues (figure 11-36). 

Figure 11-36 

La barre d'outils Langue 

| Gerer lalangue| 

Cliquez sur le bouton Gerer la langue, cliquez sur le bouton Ajouter. Choisissez la 
langue par defaut, celle qui sera utilisee si l'interface est dans une langue non prevue. 
Cliquez de nouveau sur le bouton Ajouter, et cochez les langues supplementaires. 
Vous obtenez le panneau de la figure 11-37. La langue par defaut peut etre changee 
plus tard. Vous pouvez declarer une seule ou plusieurs variantes de langues (francais 
de France, de Suisse, du Canada). Vous aurez a gerer autant de versions de textes que 
de langues ou variantes declarees. 

A present, la barre d'outils Langue vous permet de choisir la langue des textes a affi- 
cher dans l'EDI. Choisissez une autre langue : rien ha change dans l'EDI ! En effet, 
vous devez maintenant remplacer les libelles francais par leur equivalent dans la 
langue qui vous interesse. N'oubliez rien, ni le texte par defaut dans le controle Zone 
de texte, ni le libelle des boutons (au moins pour le bouton Annuler). Recommencez 
pour les langues restantes. 
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Figure 11-37 

Le panneau de Langues 




Francais (France) [Langue par defaut] 

d (Allernagne) 
Anglais (U.S.A.) 




Valeur par defaut 



La la 



' defaut est utilisee lorsque aucun environnernent linguistique localise de 
lisateur n'est disponible. En outre, toutes les chames de la langue par 
defaut sont copiees dans les ressources des langues nouvellernent ajoutees. 



z 



Choisissez le francais dans la barre d'outils Langue et executez cette macro 



rem Codell-05 . odt bibli : Langues Modulel 
Option Explicit 

Sub MainlO 

Dim dig As Object, prenom As Object, nationalite As Object 
dig = CreerDialogue("Langues", "Dialogl") 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 
prenom = dlg.getControl ("TextFieldl") 
nationalite = dlg.getControl ("ComboBoxl") 
MsgBox("Prenom : " & prenom. Peer .Text & chr(10) & _ 
"Nationalite : " & nationalite. Peer. Text) 

end if 
dig. dispose 
End Sub 

Vous avez probablement remarque que nous n'affichons pas le contenu de la pro- 
priete Text des controles Zone de texte. En effet, si l'utilisateur ne change pas un 
champ, son contenu est remplace par un texte bizarre du genre : 

Prenom : &5 .Dialogl. TextFieldl. Text 

Notre MsgBox par contre reproduit bien le texte du champ inchange. La realisation 
du mecanisme multilingue convertit toute chaine localisable en une ressource, 
sequence lui permettant de retrouver la bonne chaine dans un conteneur de res- 
sources, commun a tous les dialogues de la bibliotheque. Toutes les proprietes affi- 
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chables contenant une chaine de caracteres (par exemple, le titre du dialogue) sont 
codees ainsi. Comme on ne peut plus utiliser directement leur contenu, une solution 
simple, dans notre cas particulier, est de passer par l'objet Peer associe au controle, 
qui reflete l'affichage sur ecran. Dans le cas general, on doit utiliser un mecanisme de 
traduction. La fonction utilitaire ci-dessous renvoie le texte dans la langue utilisateur 
a partir de l'objet dialogue et du libelle code. 

Function trad(dlg As Object, libelle As String) As String 

Dim rr As Object 

rr = dl g. Model . ResourceResol ver 

trad = rr.resolveString(Mid(libelle, 2)) 

End Function 

Choisissez une autre langue dans la barre d'outils Langue, et relancez la macro : les 
textes des controles sont bien dans cette langue. Ceci permet de tester facilement les 
differentes langues du dialogue. 

Definir des messages multilingues 

II y a encore un point ennuyeux dans notre macro : le MsgBox affiche la chaine de 
caracteres « Prenom : » qui est toujours en francais. Pour afficher un texte dans la 
langue de l'utilisateur, une solution pratique est de creer et de memoriser les res- 
sources dans une Zone de liste (Li stBox) d'un dialogue. II peut s'agir d'un dialogue 
qui ne sert qua cela, et qui ne sera jamais affiche, ou d'un controle cache dans un dia- 
logue. Pour le cacher, il suffit de mettre sa propriete Step a une valeur inutilisee dans 
l'affichage du dialogue. Dans notre exemple, le dialogue et ses controles visibles utili- 
sent le Step 1, le controle invisible utilise le Step -1. Modifiez le Step du dialogue 
pour voir ce controle, et n'oubliez pas de le remettre ensuite a 1, car le Step zero du 
dialogue affiche tous les controles a la fois. 

Chaque message sera recupere a partir de son numero d'ordre (commencant a zero) 
dans la liste de choix. II est recommande de parametrer ces numeros pour eviter les 
erreurs et faciliter les relectures de code. La liste de messages peut evoluer, soit en 
rajoutant une nouvelle langue pour la bibliotheque de dialogue, soit en rajoutant de 
nouveaux messages en fin de liste pour eviter de changer les index existants. 

rem Codell-05 . odt bibli : Langues Module2 
Option Explicit 

Sub Main2() 

Dim dig As Object, prenom As Object, nationalite As Object 
Const txtPrenom = 0, txtNation = 1 
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dig = CreerDialogue("Langues", "Dialogl") 

if dig. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 
prenom = dl g .getControl ("TextFi eldl") 
national ite = dl g. getControl ("ComboBoxl") 

MsgBox(msgTrad(dlg, txtPrenom) & prenom. Peer. Text & chr(10) & _ 
msgTrad(dlg, txtNation) & nationalite. Peer. Text) 

end if 
dig. dispose 
End Sub 



Function msgTrad(dlg As Object, rangMess As Long) As String 
Dim msg As Object 

msg = dl g. getControl ("mesMessages") 
msgTrad = trad(dlg, msg. Items (rangMess)) 

End Function 

Le rang du message a traduire est transmis a la fonction msgTrad chargee de recu- 
perer le texte code et d'obtenir le texte affichable en utilisant la fonction trad vue 
precedemment. 

A present, changez la langue de l'interface utilisateur de votre logiciel OpenOffice, 
fermez OpenOffice, rechargez le document, relancez la macro : elle affiche bien 
automatiquement dans la langue correspondante, comme sur la figure 11-38. 



Figure 11-38 

Le dialogue en allemand 




Comment faire si nous avons besoin d'afficher un message multilingue en dehors de 
tout dialogue ? La solution est la meme : il suffit de ne pas lancer la methode 
execute du dialogue pour qu'il reste invisible, et cependant profiter des messages de 
la Zone de liste. 

A l'usage, vous constaterez que creer des macros avec des dialogues et textes multi- 
lingues est assez penible : il faut prevoir assez de largeur pour les controles, rediger 
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des messages independants de la syntaxe de la langue, verifier que chaque texte de 
chaque controle de dialogue est bien traduit dans toutes les langues qu'on supporte. 

Le gestionnaire de ressources, dont on utilise la methode resol veStri ng dans la 
fonction trad, est decrit dans la documentation API aux interfaces : 

• com/sun/star/resource/XStn'ngResourceResolver pour les methodes de lec- 
ture des ressources, 

• com/sun/star/resource/XStringResourceManager pour les methodes modifiant 
les ressources. 

On peut, entre autres, connaitre la langue actuellement utilisee avec 
getCurrentLocale, ou retrouver le texte correspondant a une des langues supportees 
avec resol veStringForLocale, ou modifier un de ces textes avec 
setStri ng For Locale. 

Bogues 

Le mecanisme multilingue comporte quelques anomalies, verifiez si les Issues 87330, 87336, 87412, 
88470 ont ete corrigees. 



Les services de dialogues de l'API 

Nous avons vu que le controle Selection de fichiers (Fi 1 eControl), place dans un dia- 
logue, donne a l'utilisateur le moyen de rechercher un fichier en explorant des reper- 
toires. Nous avons aussi constate qu'il est assez primitif. Des services de l'API (voir le 
tableau 11-9) offrent des possibilites plus evoluees, sans necessiter de creer une boite de 
dialogue. En fait, si on veut utiliser un de ces services dans un dialogue, on devra l'exe- 
cuter sur un evenement, par exemple suite au declenchement d'un bouton. 

Tableau 11-9 TablServices de dialogues de l'API 



com. sun . star .ui .dialogs . Fi lePicker Selection de fichier, style selon la configuration utilisateur. 


com . sun . star . ui . di al ogs . Of f i ceFi 1 ePi cker 


Selection de fichier, style OpenOffice.org. 


com . sun . star . ui . di al ogs . SystemFi 1 ePi cker 


Selection de fichier, style du systeme d'exploitation. 


com . sun . star . ui . di al ogs . Fol derPi cker 


Selection de repertoire, style selon la configuration utilisateur. 


com . sun . star . ui . di al ogs . Of f i ceFol derPi cker 


Selection de repertoire, style OpenOffice.org. 


com . sun . star . ui . di al ogs . SystemFol derPi cker 


Selection de repertoire, style du systeme d'exploitation. 
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Suivant l'option Utiliser les bortes de dialogue OpenOffice.org affichee par le menu 
Outils>Options>OpenOffice.org>General, les services FilePicker et FolderPicker affi- 
chent une boite de dialogue soit propre a OpenOffice.org, soit propre au systeme 
d'exploitation. Les variantes de ces services permettent d'imposer le style d'affichage. 

Les services de dialogues sont decrits en anglais a la page com . sun . star . ui . di al ogs 
de la documentation de l'API. Notez que le terme ui est l'abrege anglais pour inter- 
face utilisateur (user interface). 

Selectionner un fichier existant 

Cet exemple montre quelques possibilites appreciables. 

rem Codell-06.odt bibli : ChoixFich Modulel 
Option Explicit 

Sub Ouvri rUnFichier() 

Dim FP As Object, lesFichiersO As String 

FP = CreateUnoService("com. sun. star. ui .dialogs. Fil ePicker") 
FP.DisplayDi rectory = ConvertToURL("C:\Docs OpenOf fi ce\") 
FP . appendFil ter ("Textes " , "* . txt ") 

FP . appendFi 1 ter("Documents ODF" , "* . odt ; * . ods ; * . odg , * . odp") 
FP . appendFi 1 ter("Documents MS-Office", "* . doc ; * . xl s ; * . ppt") 
FP.CurrentFilter = "Documents ODF" 
FP. Title = "Choisissez le fichier a traiter" 

if FP. execute = com. sun . star . ui . di al ogs . Executabl eDi alogResul ts .OK then 
lesFichiersO = FP. Files 

MsgBox(FP.CurrentFilter , 0, "Filtre choisi") 

MsgBox(FP.DisplayDirectory, 0, "Repertoire") 

MsgBox(lesFichiersCO) , 0, "Chemin complet") 
end if 
FP. dispose 
End Sub 

Nous demandons d'abord a l'API de nous fournir un objet FilePicker. II est utilise 
comme un dialogue : la methode execute l'affiche et indique comment il a ete 
ferme ; la methode dispose libere la ressource. Ici, elle est peu utile, car nous 
sommes en fin d'execution. Avant d'afficher le dialogue, nous effectuons quelques 
initialisations, qui sont facultatives : 

• DisplayDi rectory permet de choisir un repertoire initial. II est necessaire de lui 
fournir le chemin au format URL. 

• La methode appendFi Iter ajoute des filtres de visualisation, pour ne voir que les 
noms de fichiers correspondant au nom generique indique. Le caractere * represents 
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un nombre quelconque de caracteres, le caractere ? represente un caractere quelcon- 
que. On indique plusieurs filtres simultanes en les separant par un point-virgule. 

• La propriete CurrentFilter precise le filtre a utiliser initialement, un de ceux 
precedemment definis. 

• La propriete Ti tl e sert a imposer un texte dans le titre de la fenetre de dialogue. 
Par defaut, le titre affiche est Ouvrir. 

Lors de 1' execution (voir les figures 11-39 et 11-40), vous verifiez i'efficacite de ces 
initialisations. Vous constatez que le dialogue refuse un nom de fichier inexistant. 
Ceci est normal, car nous sommes dans un dialogue destine a ouvrir un fichier. 



Figure 11-39 

Dialogue de selection 
de fichier OOo 
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Figure 11-40 

Dialogue de selection 
de fichier MS-Windows 



fichier a trailer 
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/" * resultatCSV.ods 
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/ * savePreview.ods 



(z, testHyperlinkMScv.odr. 
[ , uneBaseCalc.ods 
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Vous ne pouvez choisir qu'un seul fichier et pourtant nous avons utilise une variable 
tableau pour recueillir le nom du fichier fourni dans la propriete Files. La raison 
apparaitra dans le prochain exemple. Ici, le tableau n'a qu'un seul element, d'index 
zero, contenant le chemin complet du fichier. 

Les proprietes Cur rent Filter et Di spl ayDi rectory precisent ce que l'utilisateur a 
choisi. Remarquez le / final dans le contenu de Di spl ayDi rectory. 



Selectionner plusieurs fichiers existants 

Pour selectionner plusieurs fichiers dans le meme dialogue (figure 11-41), il suffit de 
donner la valeur True a sa propriete MultiSelectionMode. Dans ce cas, la propriete 
Fi les renverra un tableau d'un ou plusieurs elements. Executez cet exemple et notez 
bien les resultats. 

rem Codell-06.odt bibli : ChoixFich Module2 
Option Explicit 

Sub SelectionnerDesFichiersO 

Dim FP As Object, lesFichiersO As String 

Dim repCommun As String, x As Long 

FP = CreateUnoService("com. sun. star. ui . dialogs. FilePicker") 
FP.Di spl ayDi rectory = ConvertToURL("C:\Docs OpenOffi ce\") 
FP.appendFilter("Textes" , "*.txt") 

FP . appendFi 1 ter ("Documents ODF" , "* . odt ; * . ods ; * . odg , * . odp") 
FP. appendFi 1 ter ("Documents MS-Of f i ce" , "* . doc ; * . xl s ; * . ppt") 
FP.CurrentFilter = "Documents ODF" 
FP. MultiSelectionMode = True 

FP. Title = "Choisissez le ou les fichiers a traiter" 

if FP. execute = com. sun. star. ui .dialogs. ExecutableDialogResults. OK then 
lesFichiersO = FP. Files 

MsgBox(FP.CurrentFilter, 0, "Filtre choisi") 
MsgBox(FP.Di spl ayDi rectory, 0, "Repertoire") 
if UBound(lesFichiers) > 0 then 

MsgBox("Nombre de fichiers selectionnes : " & UBound(lesFichiers)) 

repCommun = lesFichiers(O) & "/" 

for x = 1 to UBound(lesFichiers) 

MsgBox(repCommun & lesFichiers(x) , 0, "Un fichier, chemin complet") 

next 
el se 

MsgBox(lesFichiersCO) , 0, "Un seul fichier, chemin complet") 
end if 
end if 
FP. dispose 
End Sub 
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Figure 11-41 

Selection de plusieurs fichiers 




Si vous avez choisi un seul fichier, le resultat est identique a l'exemple precedent. Si 
vous avez choisi plusieurs fichiers, le resultat est assez different : 

• La propriete Di spl ayDi rectory nous donne un chemin sans le / final. 

• Le premier element de la variable 1 esFi chi ers est le chemin d'acces aux fichiers, 
sans le / final. 

• Les elements suivants ne comportent que le nom et l'extension de chaque fichier 
choisi. 

Pour ces raisons, la recuperation des chemins complets des fichiers necessite une 
petite gymnastique logicielle : tester le nombre d'elements obtenus, traiter differem- 
ment le cas d'un seul fichier selectionne et le cas de plusieurs fichiers. 



Pseudo-proprietes en ecriture seule 

Les pseudo-proprietes Ti tl e, Mul ti Sel ecti onMode, Def aul tName, sont en realite les metho- 
des setTi tl e, etc. Les methodes pour la lecture getTi tl e, etc. ne sont pas disponibles, on ne peut 
done que modifier les valeurs et non les lire. 



Enregistrer un fichier 

Nous allons maintenant construire un dialogue pour choisir le nom de sauvegarde 
d'un fichier (figure 11-42). Comme seul le dialogue nous interesse, nous henregis- 
trerons rien. 

rem Codell-06 . odt bibli : ChoixFich Module3 
Option Explicit 

Sub EnregistrerUnFichierO 

Dim FP As Object, lesFichiersQ As String, FPtype(O) As Integer 
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FP = CreateUnoServi ce("com. sun . star . ui . di al ogs . Fi 1 ePi cker") 

FPtype(O) = com . sun . star . ui . dial ogs . Tempi ateDescri ption . FILESAVE SIMPLE 

FP. initial ize(FPtypeO) 

FP.DisplayDi rectory = ConvertToURL("C:\Docs OpenOf fi ce\") 
FP.DefaultName = "mon beau fi chi er . odt" 
FP . append Fi 1 ter("Textes" , "* . txt") 

FP . append Fi 1 ter ("Documents ODF" , "* . odt ; * . ods ; * . odg , * . odp") 
FP.appendFilter("Documents MS-Office", "* . doc ; * . xl s ; * . ppt") 
FP.CurrentFilter = "Documents ODF" 
FP. Title = "Sauvegarde du travail" 

if FP. execute = com. sun . star . ui . di al ogs . Executabl eDi alogResul ts .OK then 
1 esFi chi ers () = FP. Files 

MsgBox(FP.CurrentFilter, 0, "Filtre choisi") 

MsgBox(FP.DisplayDi rectory, 0, "Repertoire") 

MsgBox(lesFichiers(0) , 0, "Chemin complet") 
end if 
FP. dispose 
End Sub 

Nous utilisons la methode initialize pour preciser quel modele de dialogue nous 
allons utiliser. Plusieurs modeles sont possibles, comme nous le verrons plus bas. Pour 
des raisons de conception de l'API, la methode i ni ti al i ze n'accepte qu'un tableau de 
valeurs, bien que dans le contexte des dialogues une seule valeur soit utilisee. 

La propriete DefaultName nous sert a proposer un nom de fichier. Le bogue 
Issue 79211 sous MS-Windows fait que ce nom n'apparait pas s'il n'existe aucun 
fichier des extensions recherchees. Nous avons impose le titre du dialogue, mais par 
defaut le titre est Enregistrer sous. Si vous choisissez un fichier existant, le dialogue 
demande une confirmation. 



Figure 11-42 

Dialogue d'enregistrement 
de fichier 
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II est possible d'utiliser la selection multiple, bien que cela ne cadre pas avec l'usage 
habituel. 
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Les differents dialogues de FilePicker 

Les variantes de dialogues sont definies par des constantes nominees extremement 
longues, dont la racine est com. sun . star .ui . di alogs .Tempi ateDescri ption. 

L'etude de ces variantes laisse une impression de developpement logiciel encore en 
cours. Seulement trois d'entre elles sont utilisables facilement : 

• FILEOPEN_SIMPLE qui correspond a la valeur par defaut lorsque la methode 
i ni ti al i ze n'est pas employee, 

• FILESAVE_SIMPLE qui a deja ete vue a la section « Enregistrer un fichier », 

• FILESAVE_AUTOEXTENSION qui ajoute a la precedents une case a cocher Extension 
automatique du nom du fichier, pour utiliser la premiere des extensions indiquees 
par le filtre. 

Pour etre utilisables, les autres dialogues necessitent des developpements qui sortent 
du cadre de ce livre. De meme, il est possible d'ajouter certains boutons dans le pan- 
neau de dialogue. Nous renvoyons les developpeurs interesses a la documentation 
API du service Fi 1 ePi cker. 



Choisir un repertoire 

Le service FolderPicker est assez simple a utiliser. Le panneau resultant est repro- 
duit aux figures 11-43 et 11-44. 

rem Codell-06 . odt bibli : ChoixRep Modulel 
Option Explicit 

Sub Choi si rUnRepertoi re() 
Dim FP As Object 

FP = CreatellnoServi ce("com . sun . star . ui . dialogs. FolderPicker") 

FP.DisplayDi rectory = ConvertToURL("C:\Docs OpenOff i ce\") 

FP. Description = "Cliquez sur un repertoire" 

FP. Title = "Choisissez votre repertoire de sauvegarde" 

if FP. execute = com . sun . star . ui . di al ogs . Executabl eDi al ogResul ts .OK then 

MsgBox(FP. Directory, 0, "Chemin obtenu") 
end i f 
End Sub 

A son ouverture, le dialogue affiche le repertoire contenant celui qui est indique par 
sa propriete Di spl ayDi rectory. Actuellement, avec le dialogue propre a 
MS-Windows, ceci ne se fait pas ; voyez a ce sujet Tissue 64800. 

La propriete Title remplace le texte par defaut Selection d'un chemin. 
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La propriete Descri pti on remplace le texte par defaut Selectionnez un dossier. Avec le 
dialogue propre a OpenOffice.org la propriete Descri pti on nest pas efficace, le texte 
reste inchange. 

Le repertoire choisi par l'utilisateur est obtenu dans la propriete Di rectory, en lec- 
ture seule. II est presente sous forme d'une URL. 

La methode dispose n'existe que dans la version de dialogue propre a Open- 
Office. org, aussi on ne peut pas l'employer car le fonctionnement dependrait d'une 
configuration utilisateur. 



Figure 11-43 

Dialogue de selection 
de repertoire OOo 




Figure 11-44 

Dialogue de selection 
de repertoire MS-Windows 
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Conclusion 

Nous avons passe en revue les fonctionnalites de base des controles et boites de dia- 
logue. Les outils exposes permettent d'envisager de multiples utilisations pour creer 
des boites et assistants toujours plus simples et conviviaux pour l'utilisateur. 

Pour la simplicite de l'expose, chaque exemple de ce chapitre utilisait un nombre 
minimal de controles. Pour vous exercer, essayez de realiser des boites de dialogue 
comportant plusieurs controles et programmez la recuperation des informations uti- 
lisateur. Soignez l'aspect esthetique et l'ergonomie de vos dialogues. Inspirez-vous 
des applications sur votre PC, et en particulier de l'application OpenOffice.org : le 
panneau Rechercher et remplacer, chaque onglet du menu Outils>Options, et surtout les 
Assistants. Ces derniers utilisent des notions plus avancees, mais restent bases sur les 
controles que nous avons decrits. 

Toujours dans un esprit d'elargissement des possibilites offertes par les macros et 
l'API, le chapitre suivant traite de 1'utilisation des sources de donnees. 
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Un outil bureautique permet certes de rediger des lettres et de construire des 
tableaux, mais il doit egalement pouvoir manipuler les donnees de l'utilisateur, don- 
nees qu'on aura souvent interet a stocker dans une base de donnees. OpenOffice.org 
propose un module d'acces a ces donnees par i'intermediaire de l'outil « source de 
donnees ». 

Ce chapitre va nous permettre d'utiliser les outils mis a notre disposition pour inter- 
vener sur ces sources de donnees et done utiliser OpenOffice.org comme un moyen 
de visualisation et de modification de ces donnees. Certaines des manipulations pre- 
sentees ci-apres requierent quelques connaissances de base du langage SQL et bien 
sur des notions sur les bases de donnees. Comme ailleurs dans ce livre, nous suppo- 
sons que le lecteur connait suffisamment OpenOffice.org pour le manipuler comme 
un utilisateur confirme. 



API Reference sur les sources de donnees (en anglais) 

La documentation de I'API est decrite dans le Developer's Guide au chapitre Database Access. 

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ 

OpenOffice.org_Developers_Guide 



VOCABULAIRE Source de donnees 

Une source de donnees est un concept OpenOffice.org. El le permet d'acceder a une base de donnees (les 
tables), de memoriser des requetes pretes a I'emploi et propose des liens vers des formulaires utilisant la 
source de donnees. 
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Le concept Base 

D'extension odb, un document Base est un conteneur renfermant plusieurs sous- 
documents : 

• des informations sur la base de donnees utilisee ; 

• des requetes enregistrees ; 

• des rapports (qui sont des documents Writer) ; 

• des formulaires (qui sont des documents Writer) ; 

• eventuellement la base de donnees elle-meme. 

La base de donnees est caracterisee par son « moteur », logiciel permettant de lire et 
modifier les donnees de la base. Cette base est soit embarquee dans le document 
Base, soit externe. Le moteur gerant la base embarquee est une version adaptee de 
HSQLDB. OpenOffice.org accede a une base externe (geree par un moteur comme 
MySQL, dBase, PostGreSQL, HSQLDB, ou autre) au moyen d'un pilote (driver en 
anglais), qui peut etre disponible sous les protocoles sdbc ou DDBC. Certains pilotes 
ne permettent que de lire la base, pas la modifier (citons comme exemple celui acce- 
dant a une base Calc). 

Un formulaire peut etre soit integre dans le document Base, soit separe sous la forme 
d'un document Writer, Calc ou Draw. 

Pour avoir acces a une base embarquee, a un formulaire ou a un rapport du document 
Base, il est done necessaire d'ouvrir ce document et d'en extraire le sous-document. 
Toute la base de donnees embarquee est alors chargee en memoire vive. Si on 
modifie le contenu de la base embarquee ou d'un rapport ou formulaire embarque, le 
document Base devra etre recrit (le sous-document est remplace dans le Zip du 
fichier Base). 



Attention Compatibility 

Un document Base sauve au format ODF 1 .2 (format par defaut pour OpenOffice.org version 3) ne peut 
etre lu par une version plus ancienne que 2.4. De plus, Integration de macros dans un document Base 
evolue avec la version 3.1 d'OpenOffice.org et necessite une sauvegarde au format ODF 1.2. 



Limitations de la base de donnee embarquee 

La base de donnees embarquee est tres pratique pour une utilisation personnelle, car 
tout est integre dans un seul fichier, facilement transferable sur un autre systeme. 
Mais cette simplicite a quelques inconvenients. 

La mise a jour de l'image persistante de la base de donnees ne se fait pas a chaque 
modification ou ajout d'enregistrement, mais seulement a la fermeture de la con- 
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nexion a la base de donnees, car sauver le document Base est une operation lourde. 
Des transactions peuvent done etre perdues en cas d'anomalie. 

Cette base n'est pas faite pour memoriser des enregistrements lourds (comme les 
images jpeg) ou comportant enormement d'enregistrements : 

• La sauvegarde de la base devient de plus en plus longue car elle recrit tout le con- 
tenu systematiquement. 

• Le risque de perdre toute 1'information est important (Issue 55496). 

• II n'y a actuellement pas de fonction automatique de tassage des enregistrements. 
Pour recuperer les zones vides, il faut executer manuellement la commande SQL 
SHUTDOWN COMPACT lorsque la base commence a grossir exagerement. 

• La base entiere est deployee en RAM a l'utilisation. 

La base embarquee ne permet pas de proteger Faeces a certaines donnees par un mot 
de passe (Issue 55894). Son acces est limite a un utilisateur a la fois (Issue 42614). 

Les bases de donnees du Zip telechargeable 

Le Zip telechargeable contient dans le repertoire consacre a ce chapitre plusieurs 
fichiers que nous vous conseillons de copier et d'installer sur votre disque dur pour 
executer les exemples. Adaptez a votre systeme les adresses donnees dans les codages. 

• Le fichier BDDext . odb gere une base de donnees simple utilisant le moteur dBase ; 
la base de donnees elle-meme est dans le sous-repertoire FichdBase/. Elle est 
constitute d'une table Clients et d'une table Produits. 

• Le fichier BDDint.odb gere une base de donnees embarquee (moteur HSQL) 
ayant des tables similaires. 

• Le fichier BDDint31.odb gere une base de donnees HSQL identique, mais con- 
tient en plus des macros qui ne sont utilisables qua partir de la version 3.1 
d'OpenOffice.org. 

• le fichier uneBaseCalc.ods est une base de donnees similaire, mais fonctionnant 
sous Calc. Chaque table correspond a une feuille du classeur. 

• Le sous-repertoire bTexte/ contient un exemple de base de donnees similaire, 
sous forme d'une base plate : un fichier au format texte pour chaque table. 

Pour enregistrer la base BDDi nt sur votre ordinateur : 

1 Ouvrez le menu Outils>Options>OpenOffice.org Base>Base de Donnees. 

2 Cliquez sur le bouton Nouveau. 

3 Choisissez le fichier BDDi nt . odb . 

4 Affectez a la base le nom BDDi nt. 
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Pour la base BDDext, commencez par ouvrir le fichier BDDext . odb depuis OpenOffice. 

1 Dans le menu Edition>Base de donnees>Proprietes, ouvrez l'onglet Proprietes avan- 
cees. 

2 Indiquez le chemin vers le repertoire Fi chdBase/ sur votre ordinateur. 

3 Fermez le fichier BDDext . odb 

4 Enregistrez la base de donnees comme indique pour BDDi nt. 

Pour nos exemples, la base plate et la base Calc n'ont pas besoin d'un fichier Base. 



Methode Limitations de dBase 

L'utilisation du format dBase permet de fournir une base commune de tests pour nos exemples, mais il 
est insuffisant pour bien des usages. Pour eviter des anomalies, nous avons utilise des noms de colonnes 
de longueur limitee et en majuscules, et proscrit les caracteres accentues dans les colonnes de texte. Les 
colonnes a contenu auto-incremente n'existent pas. Les relations entre tables ne sont pas supportees. 
Vous ne pourrez profiter pleinement de la puissance d'OpenOffice.org qu'en utilisant une vraie base de 
donnees relationnelle comme la base de donnees embarquee, ou bien la base MySQL oil les jointures 
sont autorisees, et le langage SQL pleinement reconnu. 

Cependant les principes exposes dans ce chapitre sont independants du moteur de base de donnees utilise. 



Les sources de donnees 

Le chapitre Database Access du Developer's Guide est consacre a la gestion des sources 
et bases de donnees. Les objets utilises au niveau des sources de donnees sont essen- 
tiellement regroupes dans les branches de l'API : 

• com. sun. star. sdb 

• com. sun. star. sdbc 

• com. sun. star. sdbcx 



AVERTISSEMENT Usage des bases de donnees 

Les exemples donnes ici sont volontairement simplifies. Ne vous lancez pas dans la definition ou la pro- 
grammation d'une base de donnees a usage professionnel si vous n'etes pas competent dans ce 
domaine. L'economie que vous pourriez esperer realiser risque de vous couter tres cher. Laissez ce travail 
a ceux qui en font leur metier. 

Lister les sources de donnees 

Tout acces aux sources de donnees est base sur un contexte de base de donnees dispo- 
nible par le service DatabaseContext. On cree done un objet dbContexte base sur ce 
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service, a l'aide de l'instruction CreateUnoServi ce. L'objet dbContexte est l'objet 
principal a partir duquel nous allons utiliser les sources de donnees. II est equivalent a 
la fenetre de l'interface graphique a partir de laquelle toutes les sources de donnees 
sont accessibles. Cet objet est un conteneur. Sa propriete ElementNames renvoie un 
tableau des noms de sources, ce qui nous permet de les lister. 

rem Codel2-01 . odt bibli : Sources Modulel 
Option Explicit 

Sub Li sterNomDesSourcesDeDonneesO 

Dim dbContexte As Object, lesNomsO As String, i As Long 

dbContexte = CreateUnoServi ce("com . sun . star . sdb . DatabaseContext ") 

1 esNoms=dbContexte . El ementNames 

for i = 1 bound (lesNoms) to ubound(lesNoms) 

print lesNoms(i) 
next i 

print "Codage plus simple, utilisant une boucle for each" 

Dim unNom As String 

for each unNom in lesNoms 

print unNom 
next 
End Sub 

Le conteneur dbContexte est capable de retrouver une source par son nom. Ainsi, il 
possede la methode hasByName permettant d'indiquer si une source de donnee est 
presente et la methode getByName pour obtenir l'objet source. La premiere methode 
s'averera tees interessante quand nous creerons dynamiquement une source de don- 
nees afin d'eviter une duplication du nom (ce qui est interdit par l'API). Pour acceder 
a chacun des objets de la collection contenue dans dbContexte, nous utiliserons une 
deuxieme approche. 

rem Codel2-01 . odt bibli : Sources Module2 
Option Explicit 

Sub ListeSourcesDeDonneesO 

dim dbContexte As Object, MonEnum As Object, UneSource As Object 

dbContexte = CreateUnoServi ce ("com . sun . star . sdb . DatabaseContext") 
MonEnum = dbContexte. createEnumerationO 
while MonEnum. hasMoreElements 

UneSource = MonEnum. nextElement 

print UneSource. Name 
wend 
End Sub 
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En utilisant remuneration MonEnum retournee par la methode createEnumeration, 
nous constituons une liste des sources de donnees accessibles. MonEnum peut done etre 
vu comme un tableau constitue des sources de donnees presentes au niveau d'Open- 
Office.org. Cependant, il s'agit d'une sequence, et non d'un tableau, et son utilisation 
est un peu differente. 

Toute enumeration retournee par l'API possede en effet des methodes de navigation 
permettant de savoir si en parcourant cette liste, il reste des elements auxquels 
acceder (le booleen hasMoreElements) et d'acceder a l'objet suivant (par l'utilisation 
de nextEl ement). Ainsi, la boucle whi 1 e nous permet de parcourir cette enumeration 
et d'obtenir a chaque boucle une source de donnees differente. Pour connaitre celle 
que nous manipulons, nous affichons sa propriete Name. 



A RETENIR Enumeration 

De nombreux objets collections capables d'enumerer leur contenu existent dans l'API. La meme methode 
que celle decrite ici est alors employee. 



Proprietes d'une source de donnees 

Avant d'aller plus avant, voici quelques proprietes accessibles au niveau de la source 
de donnees. Nous ne donnons ici que les plus courantes, en utilisant la source de 
donnees Bibliography presente en standard dans OpenOffice.org. 

rem Codel2-01.odt bibli : Sources Module3 
Option Explicit 

Sub ProprieteSourceO 

dim nomSource As String, cr As String 

dim dbContexte As Object, maSource As Object 

cr = chr(13) ' retour a la ligne 
nomSource = "Bibliography" 

dbContexte = CreateUnoServi ce("com . sun . star . sdb . DatabaseContext") 

if dbContexte. hasByName (nomSource) then 
maSource = dbContexte . getByName (nomSource) 
MsgBox("Nom = " & maSource. Name & cr & _ 
"URL = " & maSource. URL & cr & _ 

"Mot de passe requis ? " & maSource . IsPasswordRequi red & cr & 
"En lecture seule ? " & maSource . IsReadOnly & cr & 
"Utilisateur = " & maSource. User & cr & _ 
"Mot de passe = " & maSource . Password) 

el se 
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MsgBox("La source 
endi f 
End Sub 



& nomSource & "' n'existe pas", 16) 



Apres avoir cree notre contexte de source de donnees, nous verifions que la source de 
donnees Bibliography existe bien, grace a la fonction hasByName qui renvoie True 
dans ce cas. Puis, en utilisant la fonction getByName, nous definissons la variable 
maSource attachee a la source de donnees Bi bl i ography. Nous affichons ensuite dif- 
ferentes proprietes. Une liste plus complete est reproduite dans le tableau 12-1. Vous 
trouverez de plus amples informations dans la documentation API du service 
com . sun . star . sdb . DataSource. 

Tableau 12-1 Proprietes de la source de donnees 



Name 


String 


Nom de la source de donnees. 


URL 


String 


Chemin de la source de donnees. La structure de cette URL con- 
tient les protocoles utilises, elle est exposee plus loin. 


IsPasswordRequi red 


Bool ean 


True si un mot de passe est requis. 


IsReadOnly 


Bool ean 


True si la source de donnees est declaree comme etant en lec- 
ture seule. 


User 


String 


Nom de I'utilisateur. 


Password 


Stri ng 


Mot de passe. 


Logi nTi meOut 


Long 


Nombre de secondes avant la declaration d'un echec de con- 
nexion. 


TableFilter 


Array 


Tableau de Stri ng. Liste des tables affichables. On peut utiliser 
les caracteres generiques % et ?. 


TableType Filter 


Array 


Tableau de Stri ng. Liste des types de tables affichables. Les 
types acceptes sont : TABLE, VIEW, SYSTEM TABLE. 



Creer et supprimer une source de donnees 

La methode la plus pratique et la plus rapide est bien sur d'utiliser l'assistant par le 
menu Fichier>Nouveau>Base de donnees. Ce n'est que dans des cas particuliers qu'il 
sera necessaire de creer une source de donnees par programmation. 



L'URL d'une source de donnees 

Creer une source de donnees revient avant tout a indiquer a OpenOffice.org le 
chemin d'acces aux donnees ainsi que le protocole utilise, sous la forme d'une URL. 
OpenOffice.org propose un grand nombre de connecteurs aux sources de donnees 
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qui vont influer sur la syntaxe de cette URL. L'URL se decompose ainsi : 
<protocol e> : <sous-protocol e> : <chemi n> 

Les protocoles reconnus sont : 

• sdbc - celui que nous utiliserons par la suite 

• JDBC 

Les sous-protocoles definissent le type de la base de donnees : 

• MySQL 

• Adabas 

• ODBC 

• dBase - celui que nous utiliserons par la suite 

• ADO 

• texte 

• cal c (un tableur Calc) 

• Carnet d'adresses 

• embedded : hsql db pour la base embarquee d'OpenOffice.org 
Les URL completes avec le protocole sdbc sont les suivantes : 

• document Calc : sdbc: calc : URLfi chierCalc 

• fichier texte plat : sdbc : flat: URLfi chierTexteOuRepertoi re 

• dBase: sdbc :dbase: URLfi chierDBaseOuRepertoi re 

• carnet d'adresses ThunderBird : sdbc: address :thunderbi rd : 

• carnet d'adresses Mozilla : sdbc : add ress : mozi 11a 

• carnet d'adresses LDAP : sdbc: address:! dap 

• carnet d'adresses Outlook Express(MS-Windows) : sdbc:address:outlookexp 

• carnet d'adresses Outlook (MS-Windows) : sdbc: add ress: outlook 

• base embarquee : sdbc : embedded : hsql db 

La source de donnees creee est alors listee dans le menu Outils>0ptions>0pen0ffice.org 
Base>Sources de donnees. 

Creer une source de donnees 

Void done comment creer une source de donnees utilisant une base de donnees 
externe : 

rem Codel2-01.odt bibli : Sources Module4 
Option Explicit 

Sub CreerSourceExterneQ 
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Dim dbContexte As Object, maSource As Object, monDocBase As Object 
Dim nomSource As String, cheminBdd As String, chemi nDocBase As String 

nomSource = "maBasel" 

cheminBdd = convertToURL("C:\Docs OpenOf f i ce\Fi chdBase") 
chemi nDocBase = convertToURL("C:\Docs OpenOff i ce\maPeti teBase . odb") 
dbContexte = CreateUnoServi ce ("com . sun . star . sdb . DatabaseContext") 
if not dbContexte. hasByName(nomSource) then 

maSource = dbContexte . createlnstanceO 

monDocBase = maSource . DatabaseDocument 

monDocBase . storeAsURL (chemi nDocBase , Array ()) 

dbContexte. register-Object (nomSource, maSource) 

' cette ligne qui va definir le type de base de donnees sous-jacent 
maSource. URL = "sdbc : dbase : " & cheminBdd 
1 remplir eventuell ement les autres proprietes de la base 
monDocBase. store' memoriser les caracteristiques dans le fichier Base 
el se 

MsgBox("Ce nom de source existe deja." & chr(13) & _ 
"Impossible de creer la nouvelle source.", 16) 

endi f 
End Sub 

Apres avoir cree notre contexte de source de donnees, nous verifions que la source de 
donnee n'existe pas deja. II est en effet impossible de creer deux sources de donnees 
sous le meme nom. C'est done l'objet du test avec la methode hasByName. Si ce nom 
n'est pas utilise, nous pouvons alors creer notre source de donnees. 

Nous commencons par obtenir un nouvel objet source de donnees a partir du con- 
texte de base donnees dbContexte. Cet objet expose la propriete DatabaseDocument 
qui va nous servir a definir le fichier Base conteneur de notre source de donnees. Ce 
fichier est enregistre, comme tout autre fichier OpenOffice, grace a sa methode 
storeAsUrl. L'adresse de stockage peut etre quelconque. 

La source de donnees est alors enregistree au niveau d'OpenOffice.org en utilisant la 
methode registerObject du contexte dbContexte. 

II est alors possible de modifier ses proprietes et notamment son type defini par la 
propriete URL. Dans le cas d'une base dBase, cette URL est constituee du prefixe 
sdbc : dbase : suivi de l'URL du repertoire contenant les fichiers. 

Afin de sauvegarder nos modifications sur la structure de la source de donnees, il est 
necessaire de les memoriser au niveau du fichier .odb conteneur que nous venons de 
creer. Nous appelons done la methode store de l'objet DatabaseDocument de notre 
contexte. A partir de ce point, notre source de donnees est creee. 



Construire des applications avec OpenOffice.org 

QUATRIEME PARTIE 



La creation d'une source de donnees embarquees est un peu plus simple, car la pro- 
priete URL contient une valeur fixe : 

maSource.URL = "sdbc: embedded :hsqldb" 

Bien sur, notre base de donnees embarquee est encore vide, elle ne contient aucune 
table. 

A partir d'un fichier Base 

Si on dispose deja du fichier Base, on peut creer la source en indiquant directement le 
chemin de ce fichier pour obtenir l'objet source que nous enregistrons sous le nom desire. 

rem Codel2-01.odt bibli : Sources Module5 
Option Explicit 

Sub CreerSourceDepui sOdb() 

Dim dbContexte As Object, maSource As Object 
Dim nomSource As String, cheminBdd As String 

nomSource = "maBase2" 

cheminBdd = convertTollRL("C : \Docs OpenOff i ce\uneBase . odb") 
dbContexte = CreateUnoServi ce("com . sun . star . sdb . DatabaseContext") 
if not dbContexte. hasByName (nomSource) then 

maSource = dbContexte. getByName (cheminBdd) 

dbContexte. registerObject (nomSource, maSource) 
el se 

MsgBox("Ce nom de source existe deja." & chr(13) & _ 
"Impossible de creer la nouvelle source.", 16) 

endi f 
End Sub 

Cette methode permet soit de reenregistrer une source de donnee qu'on a supprimee, 
soit d'enregistrer une source a partir d'un fichier Base transfere depuis une autre instal- 
lation. Dans ce dernier cas, si la propriete URL de l'objet source indique le chemin d'une 
base de donnees externe, il faudra eventuellement l'adapter au chemin dans la nouvelle 
configuration et sauver le fichier Base, comme decrit dans l'exemple precedent. 

A partir d'une base plate (fichier texte ou csv) 

Une base plate est une base de donnees constituee de fichiers textes. Chaque fichier 
est une table dont le nom est celui du fichier, et dont chaque ligne est un enregistre- 
ment dans la table. Les colonnes de la table sont reconnues par un caractere separa- 
teur de champ, par exemple une tabulation. Un fichier dit « csv » n'est rien d'autre 
qu'un tel fichier texte, mais avec une extension csv. Nous allons creer un fichier Base 
et enregistrer une source a partir d'un repertoire contenant un ou plusieurs fichiers 
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d'extension txt. Si la base ne comporte qu'un seul fichier, on peut mettre dans 
chemi nBdd l'adresse de celui-ci. 

rem Codel2-01.odt bibli : Sources Module6 
Option Explicit 

Sub CreerSourceBasePlateCsvO 

Dim dbContexte As Object, maSource As Object, monDocBase As Object 
Dim nomSource As String, cheminBdd As String, chemi nDocBase As String 

nomSource = "maBase3" 

cheminBdd = ConvertToURL("C:\Docs OpenOffi ce\bTexte\") ' repertoire 
chemi nDocBase = ConvertToURL("c:\Docs OpenOffi ce\maClientele.odb") 
dbContexte = CreateUnoServi ce ("com. sun .star. sdb.DatabaseContext") 
if not dbContexte . hasByName(nomSource) then 
maSource = dbContexte . createlnstanceO 
monDocBase = maSource . DatabaseDocument 
monDocBase. storeAsURL (chemi nDocBase , ArrayO) 
dbContexte. regi sterObject(nomSource , maSource) 
maSource. URL = "sdbc : flat : " & cheminBdd 
With maSource. Settings 

.Extension = "txt" ' chaque fichier .txt de cheminBdd sera une table 
. HeaderLine = True ' la premiere ligne contient les en-tetes 

. Fi el dDel i miter = chr(9) ' separateur de champ : tabulation 
. StringDel imiter = """" 1 delimiteur : un guillemet 
.Decimal Deli miter = "." ' Point decimal : 1,234,567.89 
.ThousandDel imiter = "," ' Virgule separe les milliers : 1,234,567.89 
.CharSet = "wi ndows-1252" ' codage windows-1252 
.EnableSQL92Check = False 
End With 

monDocBase. store 
else 

MsgBox("Ce nom de source existe deja." & chr(13) & _ 
"Impossible de creer la nouvelle source.", 16) 

endi f 
End Sub 

L'objet obtenu par la propriete Setti ngs de l'objet source nous sert a preciser la codi- 
fication utilisee par les fichiers constituant la base : s'il y a une ligne d'en-tete, le 
separateur decimal, le separateur de champ, etc. 

Le tableau 12-2 donne la valeur de CharSet pour les systemes les plus courants. 



Tableau 12-2 Principaux jeux de caracteres pour une base plate 
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Tableau 12-2 Principaux jeux de caracteres pour une base plate 



Jeu de caracteres 


Valeur de CharSet 


Europe occidentale (DOS/OS2-437/US) 


ibm437 


Europe occidentale (DOS/OS2-850/lnternational) 


ibm850 


Europe occidentale (DOS/OS2-863/Francais canadien) 


IBM863 


Europe occidentale (Windows-1252/WinLatin1) 


wi ndows-1252 


Europe occidentale (Apple Macintosh) 


maci ntosh 


Europe occidentale (ISO-8859-1) 


iso-8859-1 


Latin 3 (ISO-8859-3) 


iso-8859-3 


Europe occidentale (ISO-8859-14) 


iso-8859-14 


Europe occidentale (ISO-8859-1 5/EURO) 


iso-8859-15 


Unicode (16 bits) 


non disponible 


Unicode (UTF-8) 


utf-8 


Systeme (jeu de caracteres natif) 


chame vide 


Le jeu de caracteres du systeme est aussi utilise pour toute valeur non reconnue 


XXX 



Supprimer une source de donnees 

Pour supprimer la source de donnees, il suffit d'appeler la methode revokeObject du 
contexte de base de donnees, en transmettant comme argument le nom de la source 
de donnee. Attention, aucune demande de confirmation n'est demandee lors de l'uti- 
lisation de cette methode ! 



rem Codel2-01.odt bibli : Sources Module7 
Option Explicit 

Sub SupprimerSourceO 

Dim dbContexte As Object, nomSource As String 
nomSource = "maBasel" 

dbContexte = CreateUnoServi ce("com . sun . star . sdb . DatabaseContext") 

if dbContexte . hasByName(nomSource) then 
dbContexte . revokeOb j ect (nomSource) 

el se 

MsgBox("Cette source de donnees n'existe pas", 16) 
endif 
End Sub 

Cette suppression ne detruit pas le fichier Base qui etait associe a la source. II pourra 
etre necessaire de le supprimer pour nettoyer toute trace de la definition de la source 
de donnees en utilisant l'instruction Ki 1 1 de Basic par exemple. 
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Se connecter a une source de donnees 

Maintenant que nous disposons d'une source de donnees specifique declaree dans 
OpenOffice.org, nous allons voir comment l'utiliser avec les ressources de l'API. 

La premiere etape est de demander explicitement a OpenOffice.org de se connecter 
a la source en question, c'est-a-dire obtenir un objet permettant de l'utiliser. Sachez 
qu'il est parfaitement possible d'obtenir plusieurs connexions sur une meme base de 
donnees, par exemple pour conduire plusieurs interrogations en meme temps. 
L'exemple ConnecterDeconnecter presente ici utilise deux macros utilitaires que 
nous reutiliserons tout au long de ce chapitre, pour nous connecter et nous decon- 
necter de la source. 

rem Codel2-01 . odt bibli : BaseDonnees Modulel 
Option Explicit 

Sub ConnecterDeconnecterO 
Dim maConnexion As Object 

maConnexion = ConnecterSource("BDDext") 
if IsNull (maConnexion) then 

MsgBox("Source inexistante ou mot de passe incorrect", 16) 

Exit Sub 
end if 

On Error CoTo fermerConnexion 

' exemple d' utilisation de la connexion 
MsgBox (maConnexi on . Parent . Name) 

suite: 

On Error GoTo 0 
DeconnecterSource(maConnexi on) 

Exit Sub 

fermerConnexion : 

MsgBox(Error, 16) 
Resume suite 
End Sub 

La macro ConnecterSource effectue une connexion a la source dont le nom est fourni 
en argument. Nous detaillons cette macro plus bas. Elle renvoie un objet connexion, 
ou un objet Null si la connexion n'a pu etre effectuee. Cette eventualite est testee 
pour afficher un message d'erreur et arreter la macro. 

Quand une connexion est en cours, si le programme declenche une erreur (eventuel- 
lement renvoyee par le pilote de la base de donnees), il faut fermer la connexion pour 
eviter de bloquer la base, surtout si la base est embarquee. Pour cela, il est indispen- 
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sable d'effectuer un traitement d'erreur, ce que nous avons fait dans la suite du 
codage. Le principe des traitements d'erreur est explique au chapitre 6. Pour alleger 
les autres exemples, nous omettrons ensuite le traitement d'erreur, mais ne l'oubliez 
pas dans vos codages ! 

La propriete Parent d'une connexion nous donne la source de donnees gerant la base 
utilisee. Ici, nous affichons le nom de cette source. En cas d'erreur, le programme se 
poursuit a 1' etiquette fermerConnexion, oil il affiche le message d'erreur, desactive 
l'erreur en cours, et reprend la fin de traitement, qui effectue la deconnexion. 

Les routines ConnecterSource, DeconnecterSource sont declarees dans le module 
Standard du document exemple afin d'etre utilisables par les macros situees dans 
d'autres bibliotheques de ce meme document. 

rem Codel2-01.odt bibli : Standard Modulel 
Option Explicit 

Function ConnecterSource(nomSource As String, 
Optional nomUtilisateur As String, 
Optional motDePasse As String) As Object 

Dim maSource As Object, dbContexte As Object, demandePasse As Object 

dbContexte = CreateUnoServi ce ("com . sun . star . sdb . DatabaseContext") 
if dbContexte. hasByName(nomSource) then 

maSource=dbContexte.getByName(nomSource) 

if IsMissing (nomUtilisateur) then 

' demander le mot de passe, si necessaire 

demandePasse = CreateUnoServi ce ("com . sun . star . sdb . Interact ionHandl er") 
ConnecterSource = maSource. connectWithCompletion(demandePasse) 

else ' nomUtilisateur impose 

if IsMissing(motDePasse) then motDePasse = "" 

ConnecterSource = maSource. getConnection(nomUtilisateur, motDePasse) 

end if 
end if 
End Function 



Sub DeconnecterSource(maConnexion As Object) 
maConnexi on. close 
maConnexi on . di spose 
End Sub 

La fonction ConnecterSource utilise un argument obligatoire qui est le nom de la 
source, et deux arguments optionnels que sont le nom d'utilisateur et le mot de passe 
d'acces a la base. Pour une base a acces libre, le premier argument suffit. II est a noter 
qu'il n'est pas non plus necessaire de specifier utilisateur et mot de passe si la source 
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de donnees utilise le protocole ODBC et que ces informations y sont stockees. Nous 
commencons done par obtenir la source de donnees a partir de son nom. Si elle 
n'existe pas, la fonction renverra un resultat Nul 1 . 

Dans le cas ou le nom d'utilisateur n'est pas fourni, on se connecte avec la methode 
connectwithCompletion de l'objet source. Le service InteractionHandler transmis 
en argument, nous permet d'afficher automatiquement un panneau de demande de 
mot de passe si la source le requiert (voir la figure 12-1). 



Figure 12-1 

La boTte de dialogue 
d'authentification 




Dans le cas ou le nom d'utilisateur est fourni a la fonction Connecte rSource, le mot 
de passe est en principe fourni (par defaut on utilisera un mot de passe constitue 
d'une chaine de longueur nulle). La methode getConnection de l'objet source 
transmet directement le nom d'utilisateur et le mot de passe au pilote de base de 
donnees. Si les valeurs sont correctes, on se connecte a la base, sinon, la fonction 
ConnecterSource renverra un resultat Nul 1 . 

Pour fermer la connexion, nous appelons la routine DeconnecterSource, qui utilise 
comme argument la connexion en cours. La routine appelle la methode close de 
l'objet maConnexi on, puis detruit l'objet en appelant sa methode di spose. 

Comme ni la base BDext ni la base BDint ne peuvent etre protegees par un mot de 
passe, nous allons user d'un artifice logiciel pour forcer une demande de mot de passe 
dans l'exemple qui suit. 

rem Codel2-01.odt bibli : BaseDonnees Modulel 
Sub demanderMotDePasse 

1 sequence pour simuler une base avec un mot de passe 

Dim maSource As Object, dbContexte As Object 

dbContexte = CreateUnoSe rvi ce ("com . sun . star . sdb . DatabaseContext ") 

maSource=dbContexte.getByName("BDDext") 

maSource. User = "" 

maSource. Password = "" 

maSource. IsPasswordRequi red = True 
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IConnecterDeconnecterO 
End Sub 

Avant d'appeler la macro de l'exemple precedent, nous modifions temporairement 
quelques proprietes de la source. On obtient a 1' execution le panneau de la 
figure 12-1, pour lequel n'importe quel nom et mot de passe suffiront, puisque la 
base les ignore. L'annulation du dialogue, par contre, n'ouvre pas la connexion, on 
obtient un objet Null . 



PIECE Fichier de verrouillage 

Nous avons signale qu'une base embarquee HSQLDB est mono-utilisateur. C'est pour cela qu'un fichier 
de verrouillage d'extension . 1 ck apparaTt dans le repertoire contenant le fichier Base des qu'une con- 
nexion est en cours avec la base et ne disparaTt que lorsqu'elle a ete fermee. Si, a la suite d'une anomalie 
d'execution, la connexion n'a pu etre fermee, votre base restera bloquee en lecture seule. Effacer le 
fichier de verrouillage n'est pas chose aisee. En fermant completement OpenOffice ce fichier devrait dis- 
paraTtre. Dans certains cas de faute logicielle mal geree, les processus OpenOffice sof f i ce . bi n et 
sof f i ce . exe peuvent rester bloques. II faut alors les « tuer » pour retrouver un fonctionnement nor- 
mal. Si le fichier ne peut toujours pas etre efface manuellement, il faudra redemarrer le systeme d'exploi- 
tation. 



Se connecter a une base non enregistree 

Nous avons etabli une connexion a partir du nom de la source, ce qui implique que la 
base ait ete enregistree sur 1' application OpenOffice de votre ordinateur. Dans cer- 
tains cas, on peut n'avoir besoin d'une base de donnees que temporairement, ou 
celle-ci n'a pas a etre connue de l'utilisateur. II suffit alors de fournir l'adresse URL 
du fichier Base de la base de donnees. 

Dim dbContexte As Object, cheminBdd As String 
Dim maSource As Object, maConnexion As Object 

cheminBdd = convertToURL("C : \Docs OpenOff i ce\uneBase . odb") 
dbContexte = CreateUnoServi ce("com . sun . star . sdb . DatabaseContext") 
maSource = dbContexte . getByName (cheminBdd) 

maConnexion = maSource. getConnection("" , "") ' se connecter a la source 

Peut-on se connecter si on ne dispose meme pas d'un fichier Base ? C'est encore pos- 
sible, ainsi que nous allons le voir avec deux exemples courants (non exhaustifs). 

A partir d'une base Calc 

Le fichier Calc devra contenir une table par feuille, le nom de chaque table sera celui 
de l'onglet de la feuille. 
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Rappel 

Les tables d'une base Calc sont en lecture seule. Pour les modifier, il faut ouvrir le document Calc lui- 
meme, a condition qu'il n'y ait pas de connexion en cours. 



Si on ne dispose pas d'un fichier Base gerant cette base de donnees, on doit utiliser 
directement le pilote correspondant au type de la base de donnees. 

rem Codel2-01 . odt bibli : BaseDonnees ModuleC 
' parti e specifique 

Dim chefPilote As Object, pilote As Object, maConnexion As Object 

Dim cheminBdd As String, URLbdd As String 

Dim infos() As New com . sun . star . beans . PropertyVal ue 

chef Pi 1 ote = CreateUnoServi ce ("com . sun . star . sdbc . Dri verManager ") 
cheminBdd = convertToURL("C:\Docs OpenOf f i ce\uneBaseCal c . ods") 
URLbdd = "sdbc:calc:" & cheminBdd 

maConnexion = chefPilote. getConnectionWithInfo(URLbdd , infos() ) 

Le service Dri verManager se charge de trouver le pilote capable de traiter le type de 
base indique par l'URL. Sa methode getConnectionWithlnfo, ici sans option parti- 
culiere, etablit une connexion. Suivant les besoins, on peut transmettre dans i nfosO 
des structures PropertyVal ue contenant les proprietes User, Password, ou d'autres 
necessaires a un pilote particulier. La connexion obtenue est un objet 
sdbc. Connection, moins sophistique que 1' objet sdb. Connection obtenu par une 
connexion classique, mais suffisant pour interroger la base. 

A partir d'une base plate (fichier texte ou csv) 

Naturellement, on peut de la meme maniere se connecter a une base plate sans avoir 
besoin d'un fichier Base. II faut alors transmettre dans infos() un tableau de 
PropertyVal ue decrivant la structure des fichiers. Pour simplifier, nous utiliserons la 
routine utilitaire CreateProperties decrite a l'annexe B et recopiee dans la biblio- 
theque Standard du document exemple. Avec le repertoire bTexte\ d'un exemple 
precedent, les changements seront : 

rem Codel2-01.odt bibli : BaseDonnees ModuleD 

' parti e specifique 

Dim infos As Variant 

cheminBdd = convertToURL("C:\Docs OpenOff i ce\bTexte\") 
URLbdd = "sdbc: flat:" & cheminBdd 
infos = CreateProperties(Array( 

"HeaderLi ne" , True, "FieldDelimiter" , chr(9), _ 

"Stri ngDel imi ter" , "Enabl eSQL92Check" , False, _ 

"DecimalDelimiter" , "ThousandDel i mi ter" , _ 

"Extension", "txt", "CharSet", "windows-1252" )) 
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Les tables d'une base plate ne sont accessibles qu'en lecture. 



Proprietes d'une connexion 



L'objet maConnexion va desormais etre notre objet de travail principal. II expose plu- 
sieurs proprietes et methodes que nous allons explorer dans les sections suivantes. 
Signalons d'abord que vous devez penser a sauvegarder le document Base si vous 
avez modifie, ajoute, supprime un rapport, un formulaire, une requete, ou la struc- 
ture d'une base de donnees. Les modifications du contenu des tables d'une base 
embarquee HSQLDB ne sont sauvegardees automatiquement qua la fermeture de la 
connexion, aussi il peut etre necessaire d'effectuer une sauvegarde du document Base 
en cours de travail pour eviter de perdre les changements de donnees en cas d'ano- 
malie. La sauvegarde du document Base se fait comme pour un document Open- 
Office, org ordinaire, on peut le recuperer de differentes manieres : 

1 depuis la source di rectement 
monDocBase = maSource . DatabaseDocument 

' depuis la connexion, en recuperant son parent : la source 
monDocBase = maConnexion . Parent . DatabaseDocument 
' depuis un RowSet, en recuperant la connexion puis la source 
monDocBase = monRowSet . Acti veConnecti on . Parent . DatabaseDocument 

monDocBase . store ' sauvegarde du document Base 

Certaines proprietes relatives, entre autres, au pilote utilise et a la syntaxe SQL 
reconnue sont accessibles par la propriete MetaData. Ces informations etant assez 
techniques (comme le nom du pilote, sa version...), nous fournissons une macro pour 
en lister quelques-unes, mais nous ne rentrerons pas dans les details. Vous trouverez 
plus d'informations sur le contenu de MetaData dans la documentation API, a l'inter- 
face com . sun . star . sdbc .XDatabaseMetaData. 

rem Codel2-01.odt bibli : BaseDonnees Module2 
Option Explicit 

Sub afficherMetaDataO 

Dim maConnexion As Object, LesMetaDatas As Object, cr As String 
cr = chr(13) 

maConnexion = ConnecterSource("BDDext") ' essayer aussi "BDDint" 

LesMetaDatas = maConnexion . getMetaData 

with LesMetaDatas 

MsgBox("URL : " & .URL & cr & "Utilisateur : " & .UserName & cr & _ 
"Nom du produit : " & . DatabaseProductName & cr & "Version : " & _ 
.DatabaseProductVersion, 0, "Informations generales") 



Les sources de donnees 

Chapitre 12 



MsgBox("Nom : " & .DriverName & cr & _ 
"Version : " & .DriverVersion & cr & _ 
"Version majeure : " & . Dri verMajorVersion & cr & _ 
"Version mineure : " & . Dri verMi norVersion , 0, "Pilote de donnees") 
MsgBox("Delimiteur d ' i denti f i cateur : " & . Identi f i erQuoteStri ng) 
MsgBox(.SQLKeywords, 0, "Mots-cles SQL") 
MsgBox( . Numeri cFuncti ons , 0, "Fonctions numeri ques") 
MsgBox( . Stri ngFunctions , 0, "Fonctions de chaines") 
MsgBox( . SystemFunctions , 0, "Fonctions du systeme") 
MsgBox(.TimeDateFunctions, 0, "Fonctions date/heure") 
MsgBox("Supporte les transactions : " & . supportsTransactions & cr & _ 
"Supporte les transactions multiples : " & _ 
. supportsMul ti pi eTransacti ons & cr & _ 
"Seulement les transactions de donnees : " & _ 
. supportsDataMani pul ati onTransacti onsOnl y , 0 , "Transacti ons") 
end with 

DeconnecterSource(maConnexi on) 

End Sub 

Bien entendu, ce type d'information trouvera toute sa pertinence lors de l'utilisation 
d'une vraie base de donnees relationnelle (ce qui nest pas le cas avec BDDext), les 
informations accessibles etant extremement nombreuses. Vous pouvez d'ailleurs 
comparer avec la base BDDint, en modifiant 1' argument de ConnecterSource. Nous 
en donnons un tres bref apercu dans le tableau 12-3. 

Tableau 12-3 Quelques proprietes de MetaData 



URL 


String 


Repertoire et nom de fichier de la base de donnees. 


UserName 


String 


Identifiant de I'utilisateur connecte. 


DatabaseProductName String 


Type du moteur de la base de donnees. 


Database ProductVersi on 


Stri ng 


Version du moteur de la base. 


DriverName 


Stri ng 


Nom du pilote utilise. 


DriverVersion 


Stri ng 


Verson du pilote. 


SQLKeywords 


Stri ng 


Liste des mots-cles SQL reconnus et n'appartenant pas a la norme 
SQL92. 


Numeri c Functions 


Stri ng 


Liste des fonctions mathematiques reconnues dans la syntaxe SQL. 


Stri ngFuncti ons 


String 


Liste des fonctions de manipulation de chames de caracteres reconnues 
dans la syntaxe SQL. 


TimeDate Functions 


String 


Liste des fonctions date/heure reconnues dans la syntaxe SQL. 


SupportsCroupBy 


Bool ean 


True si la clause CroupBy est reconnue. 


SupportsTransaction Boolean 


True si les transactions sont reconnues. 
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La connexion sur une source de donnees donne acces a plusieurs collections permettant 
de visualiser ou manipuler sa structure. Nous nous interesserons maintenant a la collec- 
tion Tab! es et a la collection Quern es qui, elle, donne acces aux requetes pre-enregistrees. 

Les tables 

La collection Tab! es, comme son nom l'indique, nous donne acces a des objets Tab! e 
(com. sun. star. sdbcx. Table) decrivant la structure de la base. Dans une base de 
donnees, chaque table a un nom et contient des colonnes possedant chacune un nom 
et un type. Un objet Table contient done lui-meme une collection Columns, les 
colonnes. Cette collection contient quant a elle, les objets Column 
(com . sun . star . sdbcx . Col umn) donnant acces aux proprietes de chaque colonne. 

Lexemple suivant va nous permettre d'illustrer simplement les imbrications enon- 
cees. II utilise deux routines que nous detaillerons successivement. 

rem Codel2-01.odt bibli : BaseDonnees Module3 
Option Explicit 

Sub InfoTablesO 

Dim lesTables As Object, uneTable As Object, maConnexion As Object 
Dim i As Long, NombreTables As Long 

maConnexion = ConnecterSource("BDDi nt") ' essayer aussi "BDDext" 
lesTables = maConnexion .Tables 'Collection des tables de la base 
NombreTables = lesTables. Count 
MsgBox("Nombre de Tables : " & NombreTables) 

for i=0 to NombreTables -1 'Boucle sur les tables 
uneTable = lesTables(i) 

MsgBox("Examen de la table : " & uneTabl e . Name & chr(13) & _ 

"Type : " & uneTable. Type) 
Anal yserPri vi 1 eges (uneTabl e . Pri vil eges) 
Af f i cherlnf osCol onnes (uneTabl e) 
next i 

DeconnecterSource(maConnexi on) 
End Sub 

Nous recuperons la collection des tables dans la variable lesTables. Afin de par- 
courir cette collection, nous aurions pu utiliser la methode createEnumeration 
comme vu precedemment. Mais on peut aussi acceder a une table par son numero 
d'ordre avec la methode getBylndex. Avec OOoBasic, le getBylndex peut etre omis, 
comme si on indexait une variable tableau. Le nombre d'elements de la collection est 
donne par sa propriete Count. II nous suffit done d'utiliser une simple boucle FOR 
pour balayer chacune des tables. 
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L'objet lesTables estune collection nommee, la methode hasByName indique done si 
une table est presente, la methode getByName donne acces a une table par son nom, et 
la methode getElementNames (ou pseudo-propriete ElementNames en Basic) donne 
un tableau listant les noms des tables. Le codage suivant resume les possibilites de 
l'objet lesTables. 

dim listeNoms() As String, reponse As Boolean, uneTable As Object 

' Liste des noms des tables 
listeNoms = LesTabl es . getEl ement Names 
' La table achats exi ste-t-el 1 e ? 
reponse = LesTabl es . hasByName("achats") 
if reponse then 

' Acceder a une table 

uneTable = LesTabl es . getByName("achats") 
endi f 

' Acceder a la derniere table de la collection 
uneTable = 1 esTabl es . getByIndex(LesTabl es . Count-1) 
' Autre syntaxe valide en Basic 
uneTable = lesTables(lesTables. Count-1) 

La propriete Type de l'objet uneTable permet de distinguer une table ordinaire 
(valeur TABLE) d'une vue (valeur VIEW) ou d'une table systeme (valeur SYSTEM TABLE). 
Nous avons cree une vue dans la base BDDi nt, ce qui n'est pas possible avec le pilote 
dBase. 

Avant de manipuler une table, il est necessaire de connaitre les droits de l'utilisateur avec 
lequel nous sommes connectes. C'est la propriete Pri vi 1 ege qui va nous renseigner. 

rem Codel2-01 . odt bibli : BaseDonnees Module3 

Sub AnalyserPrivileges(lesPriv As Long) 
dim chaine As String 

chaine = "Privileges = " & hex(lesPriv) 

if (lesPriv and com . sun . star . sdbcx . Pri vi 1 ege . SELECT) then 

chaine = chaine & chr(13) & "SELECT" 
endi f 

if (lesPriv and com. sun . star . sdbcx . Pri vi 1 ege . INSERT) then 

chaine = chaine & chr(13) & "INSERT" 
endi f 

if (lesPriv and com. sun . star . sdbcx . Pri vi 1 ege . UPDATE) then 

chaine = chaine & chr(13) & "UPDATE" 
endi f 

if (lesPriv and com. sun . star . sdbcx. Pri vi 1 ege . DELETE) then 

chaine = chaine & chr(13) & "DELETE" 
endi f 
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if (lesPriv and com. sun . star . sdbcx . Privi 1 ege . READ) then 

chaine = chaine & chr(13) & "READ" 
endi f 

"if (lesPriv and com. sun . star . sdbcx . Privi 1 ege . CREATE) then 

chaine = chaine & chr(13) & "CREATE" 
endi f 

if (lesPriv and com. sun. star. sdbcx. Privilege. ALTER) then 

chaine = chaine & chr(13) & "ALTER" 
endi f 

if (lesPriv and com. sun . star . sdbcx . Privi 1 ege . REFERENCE) then 

chaine = chaine & chr(13) & "REFERENCE" 
endi f 

if (lesPriv and com. sun. star. sdbcx. Privilege. DROP) then 

chaine = chaine & chr(13) & "DROP" 
endi f 

MsgBox(chai ne) 
End Sub 

La propriete Privileges de l'objet LaTable retourne un entier Long qui est 1' addition 
de constantes representant les actions du groupe com. sun. star, sdbcx. Privi lege. 
Comme ces constantes sont des puissances de 2, a l'aide d'un ET logique (AND) nous 
pouvons savoir si telle ou telle action est autorisee. Nous affichons en hexadecimal la 
valeur de la propriete Privileges, en utilisant la fonction hex de Basic. Contraire- 
ment aux privileges affiches, une vue ne donne qu'un acces en lecture seule ; toute 
tentative de modification se soldera par une exception SQL. 

Les colonnes 

Dans la boucle de la macro InfoTables parcourant les tables de la collection, nous 
appelons la fonction AfficherlnfosColonnes avec l'objet uneTable en cours, afin de 
parcourir les colonnes de celle-ci. 

rem Codel2-01.odt bibli : BaseDonnees Module3 
Sub Af f i cherlnf osCol onnes (uneTabl e) 
dim lesColonnes As Object, laColonne As Object 
dim i As Long, nombreCol onnes As Long 

lesColonnes = uneTabl e .Col umns ' Collection des colonnes 

nombreCol onnes = lesColonnes. Count ' Nombre de colonnes dans la table 

for i = 0 to nombreColonnes -1 'Boucle sur les colonnes 
laColonne = lesColonnes(i) 

MsgBox("Colonne : "& laColonne. Name & chr(13) & _ 
"Type = " & laColonne.TypeName & chr(13) & _ 
"Colonne facultative : " & 1 aCol onne . IsNull abl e & chr(13) & _ 
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"Auto-increment = " & laColonne.IsAutoIncrement & chr(13) & _ 

"Valeur par defaut = " & laColonne.DefaultValue) 
next i 
End Sub 

Cette macro est basee sur le meme principe que la precedente : on recupere la collec- 
tion lesColonnes, on determine le nombre d'elements du tableau par Count et on 
boucle sur chacune des colonnes pour obtenir un objet 1 aCol onne . 

Pour chacun des colonnes, nous concatenons dans la variable chaine son nom name, 
son type TypeName et l'indication si la colonne est auto-incrementee 
i sAutoIncrement. La variable chaine est ensuite affichee a la sortie de la routine, 
quand toutes les colonnes ont ete parcourues. D'autres proprietes peuvent etre mani- 
pulees (voir le tableau 12-4). Elles sont decrites, entre autres, dans 
com . sun . star . sdbcx . Col umn. 

Tableau 12-4 Proprietes de Column 



Name 


String 


Nom de la colonne. 


Type 


Long 


Type SQL de la colonne. 


TypeName 


String 


Nom du type SQL. 


Preci sion 


Long 


Nombre de chiffres. 


Scale 


Long 


Nombre de chiffres apres la virgule decimale. 


IsNullable 


Long 


Precise si la saisie du champ est obligatoire. Si elle est facultative, la colonne 
peut alors contenir une valeur nulle. Voir le texte pour les valeurs. 


IsAutoIncrement 


Bool ean 


True si la colonne est auto-incrementee (numerotation automatique). 


Descri pti on 


Stri ng 


Description de la colonne. 


DefaultValue 


String 


Valeur par defaut, sous forme de chame de caracteres. 



La propriete IsNul 1 abl e n'est pas un Bool ean, mais contient une constante nommee. 
Les trois valeurs possibles sont : 

com . sun . star . sdbc . Col umnVal ue . NULLABLE ' valeur 0, colonne facultative 
com . sun . star . sdbc . Col umnVal ue . NO_NULLS 1 valeur 1, colonne obligatoire 
com. sun. star. sdbc. Col umnVal ue . NULLABLE_UNKNOWN ' valeur 2, indetermine 



La propriete Type est une constante nommee de la forme : 



com . sun . star . sdbc . DataType . VARCHAR 
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La definition des types est basee sur JDBC 3.0. Les valeurs possibles sont listees 
dans le tableau 12-5 avec la correspondance en types supportes par Java. Attention, 
les types Java et OOoBasic ne sont pas identiques, pour le meme nom. De plus, 
OOoBasic ne supporte pas certains types Java. 

Tableau 12-5 Types de colonne 



BIT 


boolean 


TINYINT 


byte 


SMALLINT 


short 


INTEGER 


int 


BIGINT 


long 


REAL 


float 


FLOAT 


double 


DOUBLE 


double 


NUMERIC 


j ava . math . Bi gDeci mal 


DECIMAL 


j ava . math . Bi gDeci mal 


CHAR 


Stri ng 


VARCHAR 


Stri ng 


LONGVARCHAR 


Stri ng 


DATE 


java.sql .Date 



TIME 


java. sql .Time 


TIMESTAMP 


java.sql .Timestamp 


BINARY 


byte[] 


VARBINARY byte[] 


LONGVARBINARY 


byte[] 


SQLNULL 




OTHER 




OBJECT 




DISTINCT 




STRUCT 


Struct 


ARRAY 


Array 


BLOB 


Blob 


CLOB 


Clob 


REF 


ref 



Notons egalement que la collection lesColonnes permet les memes methodes 
d'acces par nom et par index que celles illustrees pour les tables : hasByName, 
getByName, etc. 



Creer ou supprimer une table 

Si la connexion nous y autorise, nous pouvons ajouter une table par macro. Cette 
table, pour etre definie, doit au moins contenir une colonne. Nous utiliserons la base 
de donnees embarquee BDDi nt comme exemple, car elle permet de definir un index 
primaire. Nous declarerons trois colonnes de types differents, dont deux serviront 
pour l'index primaire. 

rem Codel2-01.odt bibli : BaseDonnees Module4 
Option Explicit 

Sub CreerTableO 

Dim lesTables As Object, maConnexion As Object 
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Dim descrTable As Object, descrCol As Object, descrClef As Object 

maConnexion = ConnecterSource("BDDi nt") 

lesTables = maConnexion. Tables 'Collection des tables 

MsgBox("Nombre de tables avant insertion : " & lesTables. Count) 

' Creer un descripteur de table 

descrTable = lesTables. createDataDescri ptor 

descrTable.Name = "UneNouvel 1 eTabl e" 

' Creer un descripteur d'index 

descrClef = descrTable. Keys. createDataDescriptor 
descrClef .Name = "Principal" ' nom de 1 'index 
descrClef .Type = com . sun . star . sdbcx . KeyType . PRIMARY 



' Declarer une colonne texte utilise en index primaire 
descrCol = descrTable. columns. createDataDescriptor 
descrCol . Name = "Col onneTexte" 

descrCol .Type = com. sun. star. sdbc.DataType.VARCHAR 

descrCol . Precision = 100 ' nombre maximal de caracteres 

descrTabl e . Col umns . appendByDescri ptor (descrCol ) 

descrClef .Columns. appendByDescriptor (descrCol) ' mise en index 

' Declarer une colonne en virgule flottante, non indexe 
descrCol = descrTabl e . col umns . createDataDescri ptor 
descrCol . Name = "Col onneNombre" 

descrCol .Type = com . sun . star . sdbc . DataType . DECIMAL 
descrCol . Precision = 10 ' nombre total de chiffres de la colonne 
descrCol .Scale = 6 ' nombre de chiffres apres la virgule 
descrTabl e . Col umns . appendByDescri ptor (descrCol ) 

' Declarer une colonne date utilise en index primaire 
descrCol = descrTabl e . col umns . createDataDescri ptor 
descrCol . Name = "ColonneDateHeure" 

descrCol .Type = com. sun. star. sdbc. DataType. TIMESTAMP 

descrTabl e . Col umns . appendByDescri ptor (descrCol ) 

descrClef .Columns. appendByDescri ptor(descrCol ) ' mise en index 

' Ajouter 1 'index a la description de table 
descrTabl e . Keys . appendByDescri ptor (descrCl ef ) 
' Creer la nouvelle table 
1 esTabl es . appendByDescri ptor (descrTabl e) 

MsgBox("Nombre de tables apres insertion : " & 1 esTabl es . Count) 
Af f i cherlnf osCol onnes (1 esTabl es . getByName ("UneNouvel 1 eTabl e")) 

DeconnecterSource (maConnexion) 
End Sub 
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Nous allons creer et remplir trois types d'objets descripteurs : 

• pour creer la table ; 

• pour chaque colonne de la table : 

• pour l'index primaire de la table. 

Chacun est obtenu par une methode createDataDescri ptor specialisee. La premiere 
est exposee par la collection lesTables, la deuxieme est celle de l'objet Columns de 
cette meme collection, la troisieme est celle de l'objet Keys de la collection. 

Le nom de la nouvelle table est defini par la propriete Name de son descripteur. II en est 
de meme pour le descripteur d'index (ce nom nest pas affiche dans l'interface utilisa- 
teur). Pour chaque descripteur de colonne, la propriete Name est le nom de la colonne. 

La propriete Type d'un descripteur de colonne est initialisee a une des valeurs deja 
vues au tableau 12-5. Les proprietes Precision et Scale sont significatives pour les 
types NUMERIC et DECIMAL. Le descripteur de colonne possede d'autres proprietes, 
reportez-vous au tableau 12-4. Une fois rempli, le descripteur est ajoute a l'objet 
Columns du descripteur de table, avec la methode appendByDescriptor. 

La propriete Type du descripteur d'index recoit une des trois valeurs suivantes : 

• com. sun . star . sdbcx . KeyType . PRIMARY ' index primaire 

• com. sun . star . sdbcx . KeyType . UNIQUE ' index unique 

• com. sun . star . sdbcx . KeyType . FOREIGN ' index etranger 

Pour chaque colonne faisant partie de l'index, le descripteur de colonne correspon- 
dant est ajoute a l'objet Columns du descripteur d'index. Vous remarquerez qu'il est 
possible de choisir deux colonnes non consecutives. Finalement constitue, le descrip- 
teur d'index est ajoute a l'objet Keys du descripteur de table. 

Le descripteur de table est maintenant initialise. II ne reste qua l'inserer dans la col- 
lection lesTables, toujours avec une methode appendByDescriptor, pour creer la 
nouvelle table, evidemment vide. Les modifications du document Base sont automa- 
tiquement sauvegardees. Avant de fermer la connexion, nous appelons la routine 
Affiche rlnfosColonnes vue precedemment, pour visualiser la configuration de notre 
nouvelle table. 

En cas d'anomalie, nous affichons le message d'erreur et fermons la connexion. 

Effacer une table est bien plus simple : on utilise les methodes dropByName ou 
dropBylndex de la collection lesTables. Attention, la table est supprimee meme si 
elle contient des donnees ! 

rem Codel2-01.odt bibli : BaseDonnees Module5 
Option Explicit 
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Sub SupprimerTableO 

Dim lesTables As Object, maConnexion As Object 

maConnexion = ConnecterSource("BDDi nt") 
lesTables = maConnexion. tables 'Collection des tables 
MsgBox("Nombre initial de tables : " & 1 esTabl es . Count) 
if lesTables. hasByName("UneNouvelleTable") then 

1 esTabl es . dropByName("UneNouvel 1 eTabl e") 
el se 

MsgBox("La table n'existe pas", 16) 
end if 

MsgBox("Nombre final de tables : " & 1 esTabl es . Count) 
DeconnecterSource(maConnexi on) 
End Sub 



Les requetes pre-enregistrees 

La connexion etablie donne acces a la collection des requetes enregistrees dans la 
source de donnees, les Queries. Ainsi, plutot que creer des requetes par macro, vous 
pouvez directement acceder aux requetes creees dans le gestionnaire de sources de 
donnees. Afin d'eviter toute ambiguite, nous garderons le terme de query pour ce 
type de requete, reservant le mot requite a la manipulation de veritables requetes 
SQL (comme chaines de caracteres) dans les macros. Nous allons lire et modifier la 
collection des requetes qui y sont presentes. Les queries etant propres a la source de 
donnees, il n'est pas necessaire d'ouvrir une connexion. 

rem Codel2-01 . odt bibli : BaseDonnees Module6 
Option Explicit 

Sub InfoQueriesO 

Dim lesQueries As Object, uneQuery As Object, dbContexte As Object 
Dim maSource As Object, i As Long, nombreQueri es As Long 

dbContexte = CreateUnoServi ce ("com . sun . star . sdb . DatabaseContext") 
maSource = dbContexte . getByName("BDDext") ' essayer aussi "BDDint" 
lesQueries = maSource. QueryDefinitions 
nombreQueri es = lesQueries. Count 
MsgBox("Nombre de Requetes : " & nombreQueri es) 
for i = 0 to nombreQueri es -1 'Boucle sur les requetes 
uneQuery = 1 esQueries(i) 

MsgBox (uneQuery. Command, 0, "Requete : " & uneQuery . Name) 
next i 
End Sub 

Nous constatons que la macro InfoQueries ressemble beaucoup a la macro 
InfoTables. En fait, LesQueries est une collection nommee et done toutes les 
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methodes de manipulation evoquees precedemment sont utilisables (Count, 
hasByName, getByName, dropByName...) 

L'objet de base est uneQuery du type com.sun.star.sdb.QueryDefinition. Les pro- 
prietes Name et Command suffisent a le definir. 

Ajouter ou supprimer une requete 

Pour ajouter une nouvelle requete pre-enregistree a la collection, nous aurons besoin 
d'un descripteur de requete, obtenu par la methode createlnstance de la collection. 
Apres remplissage, il sera ajoute a la collection avec la methode i nsertByName. 

rem Codel2-01.odt bibli : BaseDonnees Module7 
Option Explicit 

Sub CreerRequeteO 

Dim dbContexte As Object, maSource As Object 

Dim lesQueries As Object, descrQuery As Object, dbDoc As Object 
Const nomQuery = "Produits chers" 

dbContexte = CreateUnoServi ce("com . sun . star . sdb . DatabaseContext") 
maSource = dbContexte . getByName("BDDext") 
lesQueries = maSource. QueryDefinitions 

if not 1 esQueri es . hasByName (nomQuery) then 

'creation d'un nouvelle requete par descripteur 
descrQuery = lesQueries. createlnstance 
descrQuery .Command = _ 

"SELECT * FROM Produits WHERE Prix >= 50 ORDER BY INTITULE ASC" 
1 esQueri es . i nsertByName (nomQuery, descrQuery) 
dbDoc = maSource. DatabaseDocument 

dbDoc. store' sauver la requete dans le fichier .odb 
MsgBox("Requete enregistree : " & nomQuery) 
el se 

MsgBox("Nom deja existant - Impossible de creer la requete", 16) 
endi f 
End Sub 

Apres avoir verifie qu'il n'existe pas deja une requete du meme nom, nous deman- 
dons un descripteur de requete vierge de la forme com. sun. star. sdb. 
QueryDescri ptor. La documentation de 1API decrit les differentes proprietes du 
descripteur. Habituellement, il suffit de remplir la propriete Command avec l'instruc- 
tion SQL de la requete. Apres insertion de la nouvelle query, il est necessaire d'effec- 
tuer une sauvegarde du document Base afin de memoriser les changements. Ce 
document est obtenu a partir de l'objet source de donnees, et la sauvegarde s'effectue 
comme pour un document OpenOffice ordinaire. 
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Cette technique s'avere particulierement efficace lors de migration de bases de don- 
nees MS-Access, comme nous le verrons a la fin de ce chapitre. 

Supprimer une requete pre-enregistree se fait avec la methode removeByName de la 
collection des requetes, apres avoir verifie que le nom existe bien. Ici aussi il faut sau- 
vegarder le document Base. 

rem Codel2-01 . odt bibli : BaseDonnees Module8 
Sub SupprimerRequeteO 

Dim dbContexte As Object, maSource As Object 
Dim lesQueries As Object, dbDoc As Object 
Const nomQuery = "Produits chers" 

dbContexte = CreateUnoServi ce ("com . sun . star . sdb . DatabaseContext") 
maSource = dbContexte. getByName("BDDext") 
lesQueries = maSource. QueryDef i ni ti ons 

if 1 esQueri es . hasByName(nomQuery) then 
lesQueries . removeByName (nomQuery) 
dbDoc = maSource. DatabaseDocument 

dbDoc. store ' sauver la requete dans le fichier .odb 
MsgBox("Requete supprimee") 
el se 

MsgBox("Pas de requete de ce nom", 16) 
endi f 
End Sub 



Modifier une requete 

II est parfois utile de modifier l'instruction SQL d'une requete existante afin de 
rechercher des enregistrements dependant des besoins du moment. Par exemple, on 
peut creer avec l'interface utilisateur un etat base sur le resultat d'une requete pre- 
enregistree. Ce meme etat peut sortir d'autres selections d'enregistrements, simple- 
ment en modifiant l'instruction SQL de la requete : il suffit de modifier la com- 
mande SQL de la query. 

rem Codel2-01 . odt bibli : BaseDonnees Module9 
Option Explicit 

Sub ModifierRequete() 

Dim dbContexte As Object, maSource As Object 

Dim lesQueries As Object, uneQuery As Object, dbDoc As Object 

Const nomQuery = "Clients jeunes" 

dbContexte = CreateUnoServi ce ("com . sun . star . sdb . DatabaseContext") 
maSource = dbContexte. getByName("BDDext") 
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lesQueries = maSource.QueryDefinitions 

"if lesQueries. hasByName(nomQuery) then 
uneQuery = 1 esQueri es . getByName(nomQuery) 

uneQuery. Command = "SELECT * FROM Clients WHERE NAISS >= 1982" 
dbDoc = maSource . DatabaseDocument 

dbDoc. store ' sauver la requete dans le fichier .odb 
MsgBox("Requete modifiee") 
el se 

MsgBox("Pas de requete de ce nom" , 16) 
endi f 
End Sub 



Acceder aux donnees avec le langage SQL 

La raison d'etre d'une base de donnees est de consulter et manipuler les donnees 
quelle contient. Les donnees sont ainsi vivantes et le langage SQL nous permet 
d'extraire des constructions simples ou complexes de ces donnees. Cette section va 
nous permettre d'illustrer l'emploi du langage SQL au travers d'OpenOffice.org. A 
titre d'exemple, nous utiliserons la source de donnees BDDext fournie, tout en etant 
conscients de ses limitations, notamment a propos des jointures qui ne sont pas pos- 
sibles avec ce format. Neanmoins, ceci ne restreint en rien ce qui est dit. Utiliser les 
jointures ne releve que d'un changement de syntaxe SQL et du moment que la base 
les accepte, OpenOffice.org n'y verra aucun inconvenient. 

Dans un premier temps, nous allons utiliser des fonctionnalites du ResultSet. II faut 
savoir qu'OpenOffice.org offre aussi un objet RowSet, apportant encore plus de faci- 
lite, mais comme il est base sur le ResultSet, vous devez d'abord bien connaitre ses 
possibilites. Lutilisation du RowSet est decrite plus loin. 

Nous n'utiliserons pas la base BDDint dans ces exemples car le pilote de base embar- 
quee HSQLDB gere mal le ResultSet (Issue 77865, Issue 61869, etc.). Par contre, 
dans la section consacree au RowSet, nous emploierons la base BDDint pour utiliser la 
fonctionnalite de ResultSet que fournit un RowSet, car sa realisation est exempte de 
ces bogues. 

Quelques regies syntaxiques du SQL 

Nous ne decrirons pas les commandes SQL, des livres entiers traitent ce sujet. Nous 
rappellerons cependant que les commandes SQL sont des chaines de caracteres qui 
doivent satisfaire au moins a quatre regies : 
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1 Les noms d'elements de la base, comme le nom de table ou le nom de colonne, ne 
doivent pas utiliser de lettres accentuees, ni debuter par un chiffre. Dans la base 
BDDext, qui utilise un moteur dBase assez ancien, les noms de colonnes sont en 
majuscules pour qu'ils soient reconnus par le pilote. 

2 Le nom d'un element de la base doit etre entoure de guillemets, afin d'etre 
reconnu. Certains interpreters peuvent s'en passer dans les commandes simples. 
Pensez aux guillemets en cas d'erreur SQL apparemment injustifiee. 

3 Une valeur litterale (une chaine de caracteres) doit etre entouree d'apostrophes. Si 
cette valeur comporte elle-meme des apostrophes, chacune doit etre dupliquee. 

4 Les nombres ayant une partie decimale doivent etre ecrits avec un point decimal. 

La regie 2 est parfois systematiquement appliquee par souci de simplification logi- 
cielle. C'est le cas des commandes SQL creees par l'outil de creation de requete 
d'OpenOffice.org. C'est aussi le cas pour les commandes SQL vers une base embar- 
quee lorsqu'on utilise un simple ResultSet. Void un exemple : 

SELECT "NOM", "NAISS" FROM "Clients" WHERE "NAISS" < 1958 

La syntaxe de Basic ajoute une cinquieme regie : nous avons vu au chapitre 3 que si une 
chaine de caracteres litterale comporte des guillemets, chacun doit etre duplique. Pour 
creer une telle chaine de caracteres en Basic, il faudra ecrire une instruction du type : 

c = "SELECT ""NOM"" , ""NAISS"" FROM ""Clients"" WHERE ""NAISS"" < 1958" 
MsgBox(c, 0, "Commande SQL") 

Linstruction MsgBox affichera bien le texte de la commande SQL. 

La regie 3 est facile a respecter, meme en Basic, pour une commande SQL ecrite 
explicitement. Ici, on cherche les noms commencant par « D' » : 

c = "SELECT NOM FROM Clients WHERE NOM LIKE ' D' '%' " 

Cependant, dans une commande SQL construite par programme, la chaine litterale 
etant dans une variable, une petite routine de conversion Apos s'assurera que la 
regie 3 est respectee. 

rem Codel2-01.odt bibli : Standard Module3 
Option Explicit 

Sub TesteApos 

Dim s As String, c As String 
s = "D'%" 

c = "SELECT NOM FROM Clients WHERE NOM LIKE " & Apos(s) 
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I MsgBox(c, 0, "Commande SQL") 
End Sub 

' double les apostrophes de 1 'argument chaine, 
' puis 1'encadre entre apostrophes 
Function Apos(ByVal chaine As String) As String 
Apos = & join (split (chaine, ), ) & '"" 
End Function 

Les fonctions Basic joi n et spl it sont expliquees au chapitre 5. La regie 4 necessite 
elle aussi une petite routine Poi ntDec pour eviter une virgule decimale malencon- 
treuse, introduite par la conversion de type Doubl e vers Stri ng lorsqu'on est dans un 
environnement linguistique comme le francais de France. 

I rem Codel2-01.odt bibli : Standard Module4 
Option Explicit 

Sub TestePoi ntDec 

Dim v As Double, c As String 

v = 4.5 * 1.196 

c = "SELECT INTITULE, PRIX FROM Produits WHERE PRIX > " & PointDec(v) 
MsgBox(c, 0, "Commande SQL") 
End Sub 

'transforme la virgule decimale en point decimal 
Function Poi ntDec(ByVal txtNombre As String) As String 
PointDec = join(split(txtNombre, ","), ".") 
End Function 



Exploiter les resultats d'une requete 

Une commande SQL de requete permet d'interroger la base de donnees selon plu- 
sieurs criteres. Les informations obtenues sont disponibles dans un objet ResultSet 
(anglais pour : ensemble de resultats). II existe trois services appeles ResultSet. lis 
sont definis dans les branches de l'API : 

• com. sun. star. sdb 

• com. sun. star. sdbcx 

• com. sun. star. sdbc 

Le resultat d'une requete SQL est un objet ResultSet offrant le service sdb, qui 
inclut le service sdbcx, qui inclut lui-meme sdbc. II s'agit done de la variante la plus 
elaboree. 

Nous allons utiliser la table Clients de notre source de donnees BDDext. Notre 
requete SQL va consister a obtenir une image de la table, ordonnee selon les valeurs 
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croissantes de la colonne REF. En effet, les enregistrements de la table n'ont pas 
d'ordre particulier. Nous balayerons les resultats de la requete, dans un sens, puis un 
autre. Nous irons ensuite chercher directement un des resultats. 

Cette macro est assez longue, mais peu complexe. Nous la commenterons apres. 

rem Codel2-01 . odt bibli : avecResul tSet Modulel 
Option Explicit 

Sub Li reResultatRequeteSQLlO ' ***** base dBase BDDext 

dim maRequete As Object, resuQuery As Object, maConnexion As Object 

dim instrSQL As String, monSignet As Variant 

dim execOK As Boolean, info As String, cr As String 

cr = chr(13) ' retour a la ligne, pour les messages 

maConnexion = ConnecterSource("BDDext") 
' Texte de la requete 

instrSQL = "select * from Clients order by REF" 

maRequete = maConnexion. createStatementO ' Envoyer la requete 

resuQuery = maRequete . executeQuery(i nstrSQL) 

' Traitement du resultat 

With resuQuery 

execOK = .next' obteni r la premiere ligne 

GoSub afficher 

execOK = .next 1 ligne suivante 
GoSub afficher 

execOK = .previous' ligne precedente, done la premiere ligne 
GoSub afficher 

execOK = .last' obteni r la derniere ligne 
GoSub afficher 

execOK = . relative(-3) ' remonter de 3 lignes 
GoSub afficher 

execOK = .absolute(3) ' aller a la ligne 3 
GoSub afficher 

monSignet = .Bookmark' memoriser cette position (ligne 3) 

execOK = . relative(-9999) ' remonter au-dela du debut ! 
GoSub afficher 

' reveni r a la position du signet 
execOK = . moveToBookmark(monSi gnet) 
GoSub afficher 

execOK = . absol ute(9999) ' descendre au-dela de la fin ! 
GoSub afficher 

execOK = .first' retourner a la premiere ligne 
GoSub afficher 

' aller 3 lignes plus bas que la position du signet 
execOK = .moveRelativeToBookmark(monSignet, 3) 
GoSub afficher 
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DeconnecterSource(maConnexion) 
Exit Sub' fin du sous-programme 

afficher: ' sous-programme interne 

if execOK then 

info = "Ligne : " & . Row& " " & _ 

"Client numero = " & .Col umns(O) . Short & cr & 
"Norn = " & . Col umns.getByNameC'NOM") .String & cr & _ 
"Prenom = " & .Columns(2) .String & cr & _ 
"Annee de naissance : " & . Col umns (3) . Int 
if .isFirst then info = info & cr & "Curseur en premiere ligne" 
if .isLastthen info = info & cr & "Curseur en derniere ligne" 
el se 

info = "Deplacement non execute !" 

if .isBeforeFirst then info = info & cr & "Curseur au debut" 
if . isAfterLast then info = info & cr & "Curseur a la fin" 
end if 
MsgBox(i nfo) 
Return 
End With 
End Sub 

Donnons deux explications sur le codage employe dans la macro : 

• Dans la zone encadree par With resuQuery et End With, le mot resuQuery est 
sous-entendu quand un terme commence par un point. Par exemple, . next doit 
etre interprete par OOoBasic comme resuQuery. next. Cela allege considerable- 
ment l'ecriture (et la relecture). 

• Nous utilisons un sous-programme interne appele par GoSub. Lisez le chapitre 4 
si vous ne connaissez pas cette structure. 

Apres nous etre connectes a la source de donnees, nous utilisons la fonction 
createStatement pour obtenir l'objet maRequete qui sera capable d'effectuer une 
requete SQL : il suffit d'utiliser sa fonction executeQuery, qui prend pour argument 
l'instruction SQL. Le resultat de la requete, resuQuery, est un objet offrant le service 
com . sun . star . sdb . Resul tSet. Le reste de la macro va vous montrer les possibilites de 
cet objet. II faut savoir que le resultat d'une requete a une structure logique en lignes et 
colonnes : chaque ligne est un enregistrement, et chaque colonne est un champ du 
resultat. Notre exemple renvoie la totalite des lignes d'une table, mais en general, le 
resultat ne sera pas la copie d'une table existante, tout depend de la commande SQL. 

Linteret d'un Resul tSet est sa capacite a explorer les lignes du resultat de la com- 
mande SQL grace a un curseur interne qui permet de se positionner sur une des 
lignes du resultat. Sitot apres 1' execution de la requete, le curseur de ligne se posi- 
tionne « avant le debut » des resultats. La fonction next avance d'une ligne, c'est-a- 
dire d'un enregistrement, dans la lecture du resultat. Ainsi, suite au premier next, 
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nous sommes sur la premiere ligne (si resultat il y a). La fonction next, comme celles 
que nous verrons ensuite, renvoie une valeur True si le emplacement a pu etre realise. 
Si le curseur est sur la derniere ligne, Taction next deplace le curseur « apres la fin » et 
renvoie False. Si la commande SQL a donne un resultat nul (aucune ligne), le cur- 
seur est a la fois « avant le debut » et « apres la fin ». Le ResultSet nous offre de 
nombreuses methodes sur ces principes, dont les principales sont listees au 
tableau 12-6, vous y retrouverez celles utilisees dans l'exemple. 

Tableau 12-6 Methodes du ResultSet 



Methode 


Argument 


Resultat 




next 


aucun 


Boolean 


Deplace le curseur a la ligne suivante du resultat. Voir la 
Note 1 ci-apres. 


previous 


aucun 


Boolean 


Deplace le curseur a la ligne precedente du resultat. Voir la 
Note 1 . 


beforeFi rst 


aucun 


aucun 


Deplace le curseur avant la premiere ligne du resultat. 


i sBeforeFi rst 


aucun 


Boolean 


True si le curseur se trouve avant la premiere ligne du resultat. 


f i rst 


aucun 


Boolean 


Deplace le curseur sur la premiere ligne du resultat. Voir la 
Note 1 . 


i sFi rst 


aucun 


Boolean 


True si le curseur se trouve sur la premiere ligne du resultat. 


afterLast 


aucun 


aucun 


Deplace le curseur apres la derniere ligne du resultat. 


isAfterlast 


aucun 


Boolean 


True si le curseur se trouve apres la derniere ligne du resultat. 


last 


aucun 


Bool ean 


Deplace le curseur sur la derniere ligne du resultat. Voir la Note 1 . 


"i sLast 


aucun 


Bool ean 


True si le curseur se trouve sur la derniere ligne du resultat. 


getRow 


aucun 


Long 


Renvoie le numero de la ligne de resultat sur laquelle se 
trouve le curseur. La premiere ligne est numerotee 1 . 


absol ute 


Long 


Boolean 


Deplace le curseur sur la ligne du numero indique. Un numero 
negatif correspond a la position en numerotant en inverse 
depuis la derniere ligne : -1, -2, etc. Voir la Note 2. 


relative 


Long 


Boolean 


Deplace le curseur du nombre de lignes indique, positif ou 
negatif. Voir la Note 2. 


ref reshRow 


aucun 


aucun 


Met a jour la ligne courante de resultat avec la valeur la plus 
recente de la base de donnees. Voir la Note 3. 


row/Updated 


aucun 


Boolean 


True si la ligne courante a ete modifiee. Voir la Note 3. 


rowlnserted 


aucun 


Bool ean 


True si la ligne courante a ete inseree. Voir la Note 3. 


rowDel eted 


aucun 


Boolean 


True si la ligne courante a ete effacee. Voir la Note 3. 


IsBookmarkable 


(propriete) 


Boolean 


True si le Resul tSet permet de naviguer par signet (boo- 
kmark). 


getBookmark 


aucun 


Variant 


Renvoie un signet correspondant a la ligne courante. 
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Tableau 12-6 Methodes du ResultSet (suite) 



moveToBookmark 


Variant 


Boolean 


Deplace le curseur a la ligne indiquee par le signet en argu- 
ment. Voir la Note 1 . 


moveRelativeToBookmark 


Variant 
Long 


Boolean 


Argument 1 : signet. 

Argument 2 : nombre de lignes. 

Deplace le curseur du nombre de lignes indique, positif ou 

negatif, par rapport a la position indiquee par le signet. Voir la 

Note 2. 



Notes 

1. la fonction renvoie True si le deplacement aboutit sur une ligne existante, Fal se dans le cas con- 
traire. 

2. Une tentative de positionnement au-dela des limites amene le curseur avant la premiere ou apres la 
derniere ligne du resultat. La fonction renvoie True si le deplacement aboutit sur une ligne existante, 
Fal se dans le cas contraire. 

3. Depend des possibility de la base de donnees. 



Le ResultSet est aussi capable de memoriser le rang de la ligne courante, avec un 
signet (en anglais, bookmark). Notez que la variable de signet doit etre du type 
Variant car le contenu du signet depend de I'implementation. 

Chaque colonne du resultat est accessible par le ResultSet de plusieurs facons. La 
premiere consiste a utiliser les methodes de l'interface com. sun. star. sdbc.XRow du 
ResultSet, dont les principales sont listees au tableau 12-7. Elles gerent des 
colonnes de differents types, et recoivent en argument un index de colonne, nume- 
rate a partir de 1 en commencant a gauche. 

valeur = resuQuery.getString(3) 

Les autres methodes d'acces a une colonne utilisent la collection de colonnes obtenue 
par la pseudo-propriete Columns. On accede a une colonne par son numero d'ordre 
avec la methode getBylndex, ou en OOoBasic comme si on indexait un tableau. 
Lindex est numerate a partir de zero de gauche a droite. Lobjet colonne obtenu 
expose des fonctions similaires pour recuperer la valeur memorisee (voir de nouveau 
le tableau 12-7). Mais ici elles n'ont plus besoin d'argument. Avec OOoBasic, on 
pourra les traiter comme des proprietes en omettant le get. Les deux instructions 
suivantes sont equivalentes. 

valeur = resuQuery .Columns(2) .String 

valeur = resuQuery. getColumns. getByIndex(2) .getStringQ 
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Enfin, la collection de colonnes permet d'acceder a une colonne par son nom avec la 
methode getByName. Cette methode est la plus sure, car avec un numero d'index, 
vous pouvez vous tromper de colonne sans le detecter a 1' execution. 

valeur = resuQuery. Columns. getByName("PRENOM") .String 

En resume, on peut obtenir la valeur d'une colonne de trois manieres. Ainsi pour une 
colonne contenant un Double : 

valeur = resuQuery. getDouble(4) 1 attention : rang 1, 2, 3, etc 

valeur = resuQuery. Columns(3) .Double ' attention : rang 0, 1, 2, etc 
valeur = resuQuery. Columns. getByName("NAISS") .Double 

Tableau 12-7 Fonctions getXxx d'un ResultSet 



Fonction Type Basic 


Fonction Type Basic 


getByte 


Integer 


getBytes 


Array(Integer) 


getShort 


Integer 


getDate 


Object 


getlnt 


Long 


getTime 


Object 


getLong 


Voir texte 


getTimestamp 


Object 


getFloat 


Single 


getCharacterStream 


Object 


getDoubl e 


Doubl e 


getBi naryStream 


Object 


getBool ean 


Boolean 


getObject 


Object 


getStri ng 


Stri ng 





Dans certaines fonctions getXxx, le nom Xxx est un type API simple, qui a une cor- 
respondance en langage Java. Basic le convertit dans un de ses types ou un type 
approchant, dans la mesure du possible. Ainsi, le type String est limite a 
65 535 caracteres et la fonction getLong renvoie un entier de 64 bits (type Hyper de 
1API), qui n'existe pas en natif dans OOoBasic. 

Les fonctions getXxx sont capables de convertir la donnee reelle dans leur propre 
type de resultat : un entier de faible valeur pourrait etre recupere avec getShort, 
getFloat, getDoubl e, ou meme getByte ou getString. 

Si une colonne de table est du type BICINT, on pourra utiliser getlnt si on sait que le 
contenu est representable dans un type Basic Long. Sinon, on peut utiliser getStri ng 
qui renverra la representation decimale sous forme de chaine de caracteres, et con- 
vertir cette chaine en sous-type decimal d'un Variant. 

Dim gros As Variant 

gros = CDec(resuQuery. Columns. getByNameC'ChampBICINT") .String) 
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La methode getDate renvoie une structure Date decrite au tableau 12-8 alors que la 
methode getTime renvoie une structure Time decrite au tableau 12-9. La methode 
getTimestamp renvoie une structure DateTime qui contient les elements des deux 
tableaux precedents. 

Tableau 12-8 Structure Date 





Day 


Integer 


Jour du mois, 1 a 31, 0 pour une date vide. 


Month 


Integer 


Mois de I'annee, 1 a 12, 0 pour une date vide. 


Year 


Integer 


Annee, exemple 1975. 



Tableau 12-9 Structure Time 



HundredthSeconds 


Integer 


Centiemes de seconde, 0 a 99. 


Seconds 


Integer 


Secondes, 0 a 59. 


Mi nutes 


Integer 


Minutes, 0 a 59. 


Hours 


Integer 


Heures, 0 a 59. 



Notons aussi la methode wasNull, qui renvoie True si la derniere instruction getXxx 
a recupere une valeur SQL NULL, c'est-a-dire une colonne vide. Cette methode existe 
au niveau du ResultSet comme au niveau d'un objet colonne. 

Pour rechercher des enregistrements d'une date donnee, la syntaxe SQL depend du 
moteur de base de donnees : relisez la documentation de l'editeur du moteur que 
vous utilisez. Une autre possibility est d'effectuer une requete avec le gestionnaire de 
donnees, puis d'editer la requete en desactivant le mode Ebauche, pour voir l'instruc- 
tion SQL creee. 

La reponse a une commande SQL n'est pas toujours immediate, surtout s'il s'agit de 
commandes complexes ou d'une base sur un serveur bien charge. Par defaut, le 
executeQuery attendra indefiniment, mais il est possible de limiter le temps d'attente 
(qui s'exprime en secondes) : 

maRequete.QueryTimeOut = 5 ' cinq secondes 
resuQuery = maRequete . executeQuery(i nstrSQL) 



Si l'attente excede la limite definie, une exception SQL est declenchee. La valeur 
zero correspond a une attente sans limite. 
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Autres exemples de requetes d'interrogation 

D'autres interrogations sont possibles en utilisant des instructions SQL adequates (et 
dans une syntaxe acceptee par le pilote de la base de donnees). Void quelques exem- 
ples basiques. Pour simplifier, nous n'avons pas entoure les noms de table et colonnes 
de guillemets. 

select count(*) as nb from Clients 

Renvoie au maximum une ligne, contenant dans une colonne le nombre d'enregistre- 
ments de la table Clients. 

select libelle, prix from Produits where prix > 2.99 order by prix asc 

Recherche dans la table Produits ceux dont le prix est superieur a 2,99 et renvoie le 
resultat en indiquant le libelle et le prix, mis par ordre de prix croissant. 



Inserer un enregistrement dans une table 

L'acces aux donnees est egalement possible en ecriture. La requete SQL utilisee pour 
inserer un enregistrement est un INSERT. Pour cela, il faut utiliser une autre methode 
de l'objet requete : executeUpdate. 

Nous allons ajouter une entree supplemental dans la table Produits. Le codage 
sera plus complexe qua l'accoutumee, mais nous l'expliquerons pas a pas. 

rem Codel2-01.odt bibli : avecSQL Modulel 
Option Explicit 

Sub InsererDonneesParSQLlO ' ***** base dBase BDDext 

Dim maRequete As Object, resuQuery As Object, maConnexion As Object 

Dim nbLi gnesEcri tes As Long, indexP As Long, x As Long 

Dim LeLi belle As String, LePrix As Double, instrSQL As String 

LeLi belle = "Cant de toilette" 
LePrix = 1.2 

maConnexion = ConnecterSource("BDDext") 
'chercher la valeur maximale de REF 
maRequete = maConnexion . createStatementO 

resuQuery = maRequete . executeQuery ("sel ect REF from Produits") 
indexP = 1 

while resuQuery . next 

x = resuQuery. Columns. getByName("REF") .Int 

if x >= indexP then indexP = x +1 
wend 
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' construction de la requete d ' i nsertion 
instrSQL = "Insert into Produits " & _ 

"(PRIX, INTITULE, REF) values(" & _ 
PointDec(LePrix) & "," & Apos(LeLibelle) & "," & indexP & ")" 
' ajout du nouvel enregi strement 

nbLi gnesEcri tes = maRequete . executeUpdate(i nstrSQL) 
MsgBox("Instruction SQL :" & chr(13) & instrSQL & chr(13) & _ 

"Nombre de lignes ecrites : " & nbLi gnesEcri tes) 
DeconnecterSource(maConnexion) 
End Sub 

Pour simplifier l'exemple, LeLi be! 1 e contient un texte et LePri x contient un nombre 
reel. II nous manque une information, qui est le numero d'identite du produit. Ce 
numero doit etre unique. Dans une base de donnees plus elaboree que dBase, par 
exemple la base embarquee HSQLDB, nous aurions declare une colonne auto-incre- 
mentee par la base elle-meme et nous n aurions pas a nous en preoccuper. Ici, nous 
allons choisir une valeur superieure a toutes les valeurs d'identite deja existantes dans 
la table. Pour cela, nous allons effectuer une premiere requete SQL. 

Avec un pilote de base de donnees un peu plus evolue que celui fourni, il suffirait de 
faire une requete demandant le MAX() de la colonne REF. Ici, nous devons faire le tra- 
vail nous-memes. Nous effectuons une requete qui retourne la valeur de la colonne 
dans toutes les lignes existantes. Le resultat de la requete est explore completement 
avec des appels successifs de la methode next. A la fin de la boucle whi 1 e, la variable 
i ndexP contient une valeur superieure d'une unite a la valeur maximale trouvee. 

Letape suivante consiste a construire la requete SQL qui servira a inserer le nouvel 
enregistrement, sous forme d'une chaine de caracteres. Nous devons satisfaire aux 
regies indiquees plus haut, dans la section « Quelques regies syntaxiques du SQL » : 
la valeur LePrix comportant des decimales, nous la convertirons avec la routine 
PointDec, et le liberie sera entoure d'apostrophes grace a la routine Apos. 

Ces deux routines sont dans la bibliotheque Standard du document. La variable 
i ndexP etant une valeur entiere, la conversion implicite en Stri ng sera suffisante. 

Ayant constitue l'instruction SQL, nous la transmettons au pilote de la base de don- 
nees avec la fonction executeUpdate, qui renvoie le nombre d'enregistrements ecrits. 
Dans notre cas, ce sera un seul, si tout se passe bien. 



Piece Base multi-utilisateur 

L'exemple utilise peut engendrer des incoherences dans le cas d'une base de donnees multi-utilisateur. II 
faudrait utiliser une transaction pour couvrir I'ensemble des deux requetes, comme nous le verrons dans 
la section « Les transactions ». 



Les sources de donnees 

Chapitre 12 



Modifier un enregistrement d'unc table 

Pour modifier des enregistrements d'une table, la requete SQL doit employer la 
commande UPDATE. Attention a cette instruction, qui peut tout detruire dans votre 
table. La requete sera executee avec la methode executeUpdate. 

rem Codel2-01 . odt bibli : avecSQL Module2 
Option Explicit 

Sub ModifierDonneesParSQLlO ' ***** base dBase BDDext 

Dim maRequete As Object, resuQuery As Object, maConnexion As Object 

Dim instrSQL As String, nbLi gnesEcri tes As Long 

maConnexion = ConnecterSource("BDDext") 
' construction de la requete d'insertion 

instrSQL = "UPDATE Produits SET PRIX = 149.4 WHERE PRIX > 150" 

maRequete = maConnexion . createStatementO 

' modification des enregistrements selectionnes 

nbLignesEcrites = maRequete. executeUpdate(i nstrSQL) 

MsgBox("Nombre d'enregistrements modifies : " & nbLignesEcrites) 

DeconnecterSource(maConnexi on) 

End Sub 



Supprimer des enregistrements 

Lexemple suivant supprime tous les enregistrements de la table Produits dont le 
prix est inferieur a 1 en utilisant une instruction SQL del ete. Ne pas mettre de 
clause where reviendrait a vider completement la table. Nous utilisons la fonction 
executeUpdate, comme precedemment. 

rem Codel2-01.odt bibli : avecSQL Module3 
Option Explicit 

Sub SupprimerEnregi strementsParSQLl() ' ***** base dBase BDDext 
dim maRequete As Object, instrSQL As String, maConnexion As Object 
dim nbLi gnesTrai tees As Long 

maConnexion = ConnecterSource("BDDext") 
instrSQL = "DELETE FROM Produits WHERE PRIX < 1" 
maRequete = maConnexion . createStatementO 
nbLignesTraitees = maRequete . executeUpdate (i nstrSQL) 

MsgBox("Nombre de lignes traitees : " & nbLignesTraitees) 
DeconnecterSource(maConnexi on) 
End Sub 
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Les requetes parametrees 

Lorsque vous avez a inserer un grand nombre d'enregistrements dans une table, ou a 
effectuer des modifications avec de nombreuses instructions SQL, l'utilisation d'une 
requete parametree est recommandee, car elle reduit la charge de travail du pilote de 
la base de donnees. 

Une requete parametree est une instruction SQL dans laquelle certaines valeurs sont 
remplacees par un point d'interrogation. Dans un premier temps, l'instruction SQL est 
envoyee au pilote de la base de donnees. II en effectue l'analyse syntaxique et memorise 
une version compilee de l'instruction, puis il renvoie une reference sur cette instruction. 

Dans un deuxieme temps, a chaque insertion ou modification a realiser, la reference 
est envoyee au pilote accompagnee des valeurs manquantes. II peut alors eviter la 
phase d'analyse de l'instruction SQL. 

Le mecanisme de requete parametree est pris en charge par l'objet connexion. Dans 
cet exemple, nous ajoutons 50 enregistrements a la table stocks. Le contenu est sans 
signification, seul le principe est interessant. 

rem Codel2-01.odt bibli : avecSQL Module7 
Option Explicit 

Sub InsererDonneesParRequetePrepareeO 

Dim maRequete As Object, maConnexion As Object, x As Long 
Dim instrSQL As String 

maConnexion = ConnecterSource("BDDext") 

instrSQL = "INSERT INTO Produits (INTITULE, PRIX, REF) VALUES(? , ? , ?) " 

maRequete = maConnexi on . prepareStatement(i nstrSQL) 

for x = 1 to 50 

maRequete . setlnt(3 , 20+x) 1 valeur REF 

maRequete. setString(l, "Objet" & x) 1 valeur INTITULE 

maRequete. setDouble(2, Fi x(rnd*50000)/100) ' valeur PRIX 
maRequete . execute 

next 

maRequete . di spose 
DeconnecterSource (maConnexi on) 
End Sub 

Les variables SQL sont remplies avec des instructions setXxx dont le premier argu- 
ment est le rang (debutant a 1) du point d'interrogation dans l'instruction SQL, et le 
deuxieme argument est la valeur elle-meme. Dans notre cas, la premiere variable doit 
etre du texte, la deuxieme est un entier. II existe autant de methodes setXxx que de 
methodes getXxx listees au tableau 12-7, plus la methode setNull. 

La valeur d'une variable SQL est conservee jusqu'a une nouvelle affectation. La 
methode clearParameters permet de reinitialiser toute modification des parametres. 
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Acceder aux donnees avec un ResultSet 

Au debut de la section precedente, nous avons vu que l'interrogation d'une base de 
donnees renvoie un ResultSet qui permet d'explorer l'ensemble des resultats. Ce 
meme ResultSet permet alors d'ajouter, de modifier ou de supprimer des enregistre- 
ments a volonte, par programmation, sans utiliser d'autre instruction SQL. 



Inserer un enregistrement dans une table 

La premiere partie du codage est identique a l'exemple d'insertion utilisant SQL. Ici 
cependant, notre instruction SQL va recuperer toute la table Produits. Le resultat 
de la requete SQL nous servira pour ajouter un enregistrement. 

rem Codel2-01 . odt bibli : avecResul tSet Module2 
Option Explicit 

Sub InsererDonneesParResul tSetl() 1 ***** base dBase BDDext 

Dim maRequete As Object, resuQuery As Object, maConnexion As Object 

Dim LeLi belle As String, LePrix As Double, indexP As Long, x As Long 

LeLi belle = "Cant de toilette" 
LePrix = 1.2 

maConnexion = ConnecterSource("BDDext") 
' chercher la valeur maximale de REF 
maRequete = maConnexion . createStatementO 

resuQuery = maRequete . executeQuery ("sel ect * from Produits") 
indexP = 1 

while resuQuery . next 

x = resuQuery. Columns. getByName("REF") .Int 

if x >= indexP then indexP = x +1 
wend 

' ajout du nouvel enregistrement 

resuQuery .moveToInsertRow ' aller a la zone de preparation 

resuQuery . Col umns . getByName(" PRIX") . updateDoubl e(LePri x) 
' resuQuery. Columns(2) .updateDouble(LePrix) ' equivalent 
' resuQuery. updateDoubl e(3 , LePrix) ' equivalent 

resuQuery .Col umns . getByName(" INTITULE") . updateSt ring (LeLi bel 1 e) 
resuQuery . Col umns . getByName("REF") . updatelnt (i ndexP) 

resuQuery. insertRow ' inserer 1 ' enregi strement dans la table 

DeconnecterSource(maConnexi on) 
End Sub 

Dans un premier temps, nous nous positionnons dans une zone speciale, qui est la 
ligne d'insertion, grace a la methode moveToInsertRow. Puis, nous allons remplir 
chaque colonne du nouvel enregistrement avec des methodes updateXxx. Ces 
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methodes constituent le pendant des fonctions getXXX que nous avons deja vues, 
mais avec un argument supplemental, a savoir la valeur a placer dans la colonne. 
Nous avons choisi les methodes de l'objet colonne afin de profiter de faeces par le 
nom de colonne, mais des methodes equivalentes existent aussi pour le ResultSet. 
Comme nous modifions directement chaque colonne sans passer par i'interpreteur 
SQL, les regies concernant les apostrophes et point decimal ne s'appliquent pas. 

Pour terminer, la ligne d'insertion completee est inseree physiquement dans la table 
avec la methode insertRow. Nous ne 1' avons pas employee ici, mais, apres avoir 
insere un ou plusieurs enregistrements, la methode moveToCurrentRow permet de 
revenir au point ou on en etait dans le ResultSet. 



Modifier un enregistrement d'unc table 

Par rapport a la version utilisant SQL, nous avons toute latitude pour effectuer par 
programmation des evaluations complexes des modifications a realiser. Pour rester 
simple, nous allons appliquer une hausse de 25 % au prix du premier article que nous 
trouverons dans la table Produits. 

rem Codel2-01.odt bibli : avecResul tSet Module3 

Sub Modi f i erDonneesParResul tSetlO 1 ***** base dBase BDDext 

Dim maRequete As Object, resuQuery As Object, maConnexion As Object 

Dim instrSQL As String, unPrix As Double, LeLibelle As String 

maConnexion = ConnecterSource("BDDext") 

' Texte de la requete 

instrSQL = "select * from Produits" 

maRequete = maConnexi on . createStatement () ' Envoyer la requete 

resuQuery = maRequete . executeQuery(i nstrSQL) 

if resuQuery . next then 

LeLibelle = resuQuery . Col umns . getByName("INTITULE") . Stri ng 
unPrix = resuQuery . Col umns . getByName("PRIX") . Doubl e 
unPrix = unPrix * 1.25 ' hausse de 25% 
resuQuery . Col umns . getByName("PRIX") . updateDoubl e(unPri x) 
resuQuery . updateRow' transferer dans la table 
MsgBox("Produit modifie : " & LeLibelle) 

end if 

DeconnecterSource (maConnexi on) 
End Sub 

Apres execution de la requete, nous utilisons la fonction next pour nous positionner 
sur la premiere ligne (si le resultat de la requete est vide, on ne fera rien). Nous recu- 
perons le libelle et le prix de l'article. Apres application de la hausse, nous utilisons 
updateDoubl e pour mettre a jour la colonne. Mais ceci ne modifie pas la table, car 
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nous travaillons sur une zone tampon. Nous pourrions modifier ainsi d'autres 
colonnes. Puis nous transferons la totalite de la ligne modifiee dans la table avec la 
methode updateRow. 

Dans une application plus complexe, vous pouvez avoir besoin d'annuler des modifi- 
cations en cours et recommencer tous les updateXXX. Ceci est possible avant d'exe- 
cuter updateRow ; il suffit d'employer la methode cancel RowUpdates. 



Les valeurs nulles 

Une colonne d'une table peut accepter une valeur Nul 1, ce qui signifie « absence de valeur ». Ceci est 
different d'une valeur zero ou d'une chame de caracteres vide. Pour « remplir » une colonne avec une 
valeur Nul 1, employez la methode updateNul 1 au lieu d'un updateXxx. 



Supprimer des enregistrements 

Pour simplifier l'exemple, nous presenterons la suppression de l'enregistrement de 
rang 2 dans le ResultSet. II va de soi qu'on peut choisir a volonte le ou les enregis- 
trements a supprimer. 

rem Codel2-01 . odt bibli : avecResul tSet Module4 
Option Explicit 

Sub EffacerDonneesParResul tSetl() ' ***** base dBase BDDext 

Dim maRequete As Object, resuQuery As Object, maConnexion As Object 

Dim instrSQL As String, LeLi belle As String 

maConnexion = ConnecterSource("BDDext") 

instrSQL = "select * from Produits" ' Texte de la requete 
maRequete = maConnexion . createStatementO 

resuQuery = maRequete . executeQuery(i nstrSQL) ' Envoyer la requete 
if resuQuery. absolute(2) then 

LeLibelle = resuQuery . Col umns (1) . Stri ng 

resuQuery. deleteRow' supprimer de la table 

MsgBox("Produit supprime : " & LeLibelle) 
end if 

DeconnecterSource 
End Sub 

Les differentes capacites des ResultSet 

Dans nos exemples, nous utilisons un ResultSet avec ses possibilites par defaut. 
Celles-ci sont des proprietes de l'objet requete. La propriete ResultSetType possede 
une valeur parmi trois (constantes nominees) : 
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I com . sun . star . sdbc . Resul tSetType . FORWARDJDNLY 

I com . sun . star . sdbc . Resul tSetType . SCROLL_INSENSITIVE 
com . sun . star . sdbc . Resul tSetType . SCROLL_SENSITIVE 

La premiere valeur n'autorise que les emplacements vers les lignes suivantes. La 
deuxieme valeur est celle utilisee par defaut avec notre pilote. La difference entre la 
deuxieme et la troisieme est qu'un ResultSet SCROLL_SENSITIVE se met a jour des 
modifications effectuees par d'autres utilisateurs de la base de donnees. Le pilote dBase 
que nous utilisons pour la base BDDext initialise le ResultSet a SCROLL_INSENSITIVE 
alors que le pilote de la base embarquee BDDi nt l'initialise a FORWARD_ONLY. 

La propriete ResultSetConcurrency possede une valeur parmi deux : 

com . sun . star . sdbc . Resul tSetConcu rrency . READ_ONLY 
com. sun . star . sdbc . Resul tSetConcu rrency . UPDATABLE 

La premiere valeur indique que le resultat est en lecture seule, alors que le deuxieme 
permet de modifier. La deuxieme valeur est celle utilisee par defaut avec le pilote dBase, 
alors que le pilote de la base embarquee utilise seulement la valeur READ_ONLY, ce qui 
limite singulierement l'utilite de son ResultSet. Si on souhaite une valeur particuliere 
acceptable park pilote, les proprietes Resul tSetType et ResultSetConcurrency doi- 
vent toutes deux etre initialisers avant d'executer l'instruction SQL. 



Acceder aux donnees avec un RowSet 

Un RowSet possede toutes les possibilites d'un ResultSet, mais il integre en plus un 
objet requete SQL et de nouvelles fonctionnalites. C'est cette approche que nous 
allons maintenant explorer. Ici nous pourrons utiliser aussi bien la base BDDext que la 
base BDDi nt. 

Se connecter a la base de donnees 

Pour qu'un RowSet soit utile, il doit etre connecte a une source de donnees. II existe 
plusieurs manieres de proceder : soit le RowSet se charge d'etablir une connexion vers 
la source de donnees, soit il utilise une connexion deja etablie. 

Les premiers exemples incluent un traitement d'erreur. Nous l'omettrons dans les 
autres exemples afin d'aller a l'essentiel, mais ne l'oubliez pas dans vos codages ! 
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Le RowSet etablit la connexion 

Nous utiliserons la base embarquee, le principe est identique pour une base externe. 

rem Codel2-01.odt bibli : avecRowSet Modulel 
Option Explicit 

Sub CreerRowSetAutonome2 () ' ***** base embarquee BDDint 
Dim unRowSet As Object 

UnRowSet=createUnoServi ce("com. sun . star . sdb . RowSet") 
With unRowSet 

.DataSourceName = "BDDint" 

.User = "" 

.Password = "" 

' preciser l'origine des donnees 

. CommandType = com. sun. star. sdb. CommandType. TABLE 

.Command = "Clients" 

On Error GoTo fermerConnexion 

.execute' effectuer la requete implicite 

1 analyser le resultat avec le RowSet integre 

.next ' afficher le premier enregi strement 

MsgBox("Nom = " & . Col umns . getByName("Nom") . Stri ng) 

sui te : 

On Error GoTo 0 

.dispose' detruire le RowSet et sa connexion 
Exit Sub 

fermerConnexion : 

MsgBox(Error , 16) 

Resume suite 
End With 
End Sub 

Nous commencons done par creer un objet UnRowSet vierge en utilisant le service 
com. sun. star. sdb. RowSet. La propriete DataSourceName est initialisee avec le nom 
de la source de donnees. Si la base est protegee par mot de passe, on ajoute les para- 
metres de connexion necessaires dans les proprietes User et Password (dans notre cas 
les instructions correspondantes sont inutiles). Ainsi, le RowSet nous affranchit de 
tout le travail d'etablissement de connexion. La tache a accomplir par le RowSet est 
precisee avec deux proprietes : CommandType, de type Long, et Command, de type 
Stri ng. La premiere recoit une constante nommee de la forme : 

com . sun . star . sdb . CommandType .TABLE 
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Le contenu de la propriete Command depend de ce choix, ainsi que le montre le 
tableau 12-10. 



Tableau 12-10 Relations entre Command et CommandType 



CommandType Agit sur Contenu de Command 


TABLE 


Une table de la source de donnees. 


Le nom de la table. 


QUERY 


Une requete pre-enregistree. 


Le nom de la requete pre-enregistree. 


COMMAND 


Une requete SQL. 


Une chame de caracteres contenant la requete. 



Dans cet exemple, nous choisissons la constante TABLE et indiquons dans la propriete 
Command le nom de la table Clients. En fait, notre RowSet va deduire de ce choix 
l'instruction SQL implicite : 



SELECT * FROM Clients 

Nous voyons done que les trois possibilites reviennent a demander l'execution d'une 
instruction SQL. Ce sera fait en appelant la methode execute. A titre de demonstra- 
tion, nous affichons le nom du premier client obtenu dans le ResultSet integre au 
RowSet. Pour finir, nous detruisons la ressource RowSet avec sa methode dispose, ce 
qui ferme la connexion a la base de donnees. 

Au lieu de fournir le nom d'utilisateur et mot de passe en clair dans le programme, il 
est possible de les demander a i'utilisateur avec une boite de dialogue standardised. 

rem Codel2-01.odt bibli : avecRowSet Modulel 

Sub CreerRowSetAutonome3() ' ***** base embarquee BDDint 
Dim unRowSet As Object, demandePasse As Object 

' ce codage ne sert qu'a forcer 1 'usage d'un mot de passe 
Dim dbContexte As Object, maSource As Object 

dbContexte = CreateUnoServi ce("com . sun . star . sdb . DatabaseContext") 
maSource=dbContexte. getByName("BDDi nt") 

maSource.IsPasswordRequired = True ' forcer 1 'usage du mot de passe 
UnRowSet=createUnoServi ce("com . sun . star . sdb . RowSet") 

demandePasse = CreateUnoService("com . sun . star . sdb . InteractionHandl er") 

With unRowSet 

. DataSourceName = "BDDint" 

.CommandType = com. sun. star. sdb. CommandType. TABLE 

.Command = "Clients" 

On Error CoTo fermerConnexion 

. executeWi thCompl eti on (demandePasse) 

. next 
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MsgBox("Nom = " & . Col umns . getByName("Nom") . Stri ng) 
suite: 

On Error CoTo 0 
. di spose 
Exit Sub 
fermerConnexion : 
MsgBox(Error , 16) 
Resume suite 
End With 

Une base embarquee ne supportant pas la protection par mot de passe, nous rendons arti- 
fkiellement obligatoire celui-ci en modifiant temporairement la source de donnees. Le 
service Interacti onHandl er nous fournit un objet permettant le dialogue avec l'utilisa- 
teur. La methode executeWi thCompl eti on du RowSet se charge alors d'utiliser le service 
de dialogue de mot de passe et le panneau de la figure 12-1 (voir page 679) apparait. 

Se connecter a une base non enregistree 

Dans ce cas il suffit de mettre dans la propriete DataSourcename l'URL du fichier 
Base. 

Dim cheminBdd As String 

cheminBdd = convertTollRL("C:\Docs OpenOf f i ce\uneBase . odb") 
unRowSet.DataSourceName = cheminBdd 



Utiliser une connexion existante 

Si une connexion est definie par ailleurs dans votre code, elle peut etre reutilisee par 
le RowSet, ce qui permet d'economiser les ressources du systeme. II est tout a fait pos- 
sible de greffer plusieurs RowSet sur la meme connexion. Dans i'exemple, nous sup- 
posons que le programme principal etablit la connexion, effectue un certain travail, 
puis appelle un sous-programme qui a besoin d'un RowSet. 

rem Codel2-01.odt bibli : avecRowSet Module2 
Option Explicit 

Sub ProgrammePri nci pal 
Dim maConnexion As Object 

maConnexion = ConnecterSource("BDDi nt") 

' on suppose que la connexion sert a autre chose avant d'arriver ici! 

CreerRowSetGref fe(maConnexion) 

' autre traitement eventuel avant deconnexion 

DeconnecterSource (maConnexion) 

End Sub 
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Sub CreerRowSetGreffe(connexion As Object) ' ***** base embarquee BDDint 
Dim unRowSet As Object 

unRowSet = createUnoService("com. sun. star. sdb . RowSet") 
On Error GoTo fermerRowSet 
With unRowSet 

. ActiveConnection = connexion 

.CommandType = com . sun . star . sdb . CommandType .TABLE 
.Command = "Clients" 

.execute ' effectuer la requete implicite 

. afterLast ' aller au-dela du dernier enregi strement 

if . IsRowCountFinal then 

MsgBox("Nombre d'enregistrements : " & .RowCount) 

if .absolute(3)then ' exemple d ' uti 1 i sati on du ResultSet integre 

MsgBox("Client : " & . Columns. getByName("Nom") .String) 
end if 

el se 

MsgBox("Erreur, fin de table pas atteinte !", 16) 
end if 
suite: 

On Error CoTo 0 

.dispose ' detruire le RowSet 

Exit Sub 

fermerRowSet : 

MsgBox(Error, 16) 

Resume suite 
End With 
End Sub 

Nous reprenons notre routine ConnecterSource, qui nous renvoie un objet con- 
nexion. II est transmis en argument du sous-programme CreerRowSetGreffe puis 
affecte a la propriete ActiveConnection du RowSet, qui peut ainsi l'utiliser. 

Nous profitons de l'exemple pour vous montrer une autre caracteristique du RowSet : 
la propriete RowCount indique le nombre de lignes lues. La propriete 
IsRowCountFinal vaut True si toutes les lignes ont ete lues, et done si RowCount 
indique le nombre total de lignes. Ici, ce nest pas tres utile, mais si, par la suite, vous 
inserez et/ou supprimez de multiples enregistrements, RowCount sera mis a jour. 



Explorer les resultats d'une requete 

L'exemple realise plus haut avec une commande SQL et un ResultSet est aussi reali- 
sable avec un RowSet. II suffit de se rappeler qu'un RowSet est aussi un ResultSet. 
Mais ici, toutes les fonctionnalites sont utilisables avec la base embarquee, alors que 
ce n'est pas le cas avec ResultSet. 
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rem Codel2-01 . odt bibli : avecRowSet Module3 
Option Explicit 

Sub Li reResultatRequeteSQL2() 1 ***** base embarquee BDDint 

Dim maRequete As Object, resuQuery As Object, unRowSet As Object 

Dim instrSQL As String, monSignet As Variant 

Dim execOK As Boolean, info As String, cr As String 

cr = chr(13) ' retour a la ligne, pour les messages 

UnRowSet=createUnoServi ce ("com. sun . star . sdb . RowSet") 
With unRowSet 

. DataSourceName = "BDDint" 

. CommandType = com. sun. star. sdb. CommandType. COMMAND 
.Command = "select * from Clients order by Norn" 
On Error GoTo fermerConnexi on 
.execute ' Envoyer la requete 
' Traitement du resultat 

execOK = .next ' obteni r la premiere ligne 
GoSub afficher 

execOK = .next ' ligne suivante 
GoSub afficher 

execOK = .previous ' ligne precedente, done la premiere ligne 
GoSub afficher 

execOK = .last ' obteni r la derniere ligne 
GoSub afficher 

execOK = . relative(-3) ' remonter de 3 lignes 
GoSub afficher 

execOK = .absolute(3) ' aller a la ligne 3 
GoSub afficher 

monSignet = .Bookmark ' memoriser cette position (ligne 3) 

execOK = . relative(-9999) ' remonter au-dela du debut ! 
GoSub afficher 

' reveni r a la position du signet 
execOK = . moveToBookmark(monSi gnet) 
GoSub afficher 

execOK = . absol ute(9999) ' descendre au-dela de la fin ! 
GoSub afficher 

execOK = .first ' retourner a la premiere ligne 
GoSub afficher 

1 aller 3 lignes plus bas que la position du signet 
execOK = .moveRelativeToBookmark(monSignet, 3) 
GoSub afficher 



suite: 

On Error GoTo 0 

.dispose ' detruire le RowSet 

Exit Sub ' fin du sous-programme 
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f ermerConnexi on : 
MsgBox(Error , 16) 
Resume suite 

afficher: ' sous-programme interne 

if execOK then 

info = "Ligne : " & .Row & " " & _ 

"Client numero = " & .Columns(O) .Short & cr & _ 
"Norn = " & . Col umns . getByName("Nom") . Stri ng & cr & _ 
"Prenom = " & .Columns(2) .String & cr & _ 
"Annee de naissance : " & . Col umns (3) . Date . Year 
if .isFirst then info = info & cr & "Curseur en premiere ligne" 
if .isLast then info = info & cr & "Curseur en derniere ligne" 
el se 

info = "Deplacement non execute !" 

if . i sBeforeFi rst then info = info & cr & "Curseur au debut" 
if .isAfterLast then info = info & cr & "Curseur a la fin" 
end if 
MsgBox(i nfo) 
Return 
End With 
End Sub 

La duree maximale d'attente d'execution de la commande est specifiee par la pro- 
priete QueryTimeOut du RowSet. On la modifie ainsi : 

unRowSet .QueryTimeOut =5 ' cinq secondes 



Inserer un enregistrement dans une table 

Avec la base embarquee BDDint, la colonne Ref etant auto-incremente, il n'est pas 
necessaire de lui dormer une valeur, ce qui simplifie les choses par rapport a la base 
BDDext. Pour le reste, les methodes employees sont celles du ResultSet. 

rem Codel2-01.odt bibli : avecRowSet Module4 
Option Explicit 

Sub InsererDonneesParRowSet2() ' ***** base embarquee BDDint 

Dim maRequete As Object, unRowSet As Object 

Dim LeLibelle As String, LePrix As Double, EnStock As Long 

LeLi belle = "Gant de toilette" 
LePrix = 1.2 
EnStock = 250 
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UnRowSet=createllnoServi ce("com . sun . star . sdb . RowSet") 
With unRowSet 

.DataSourceName = "BDDint" 

.CommandType = com. sun. star. sdb. CommandType . TABLE 

.Command = "Produits" 

.execute 

'ajout du nouvel enregistrement 

.moveToInsertRow ' aller a la zone de preparation 
.Col umns .getByName("Prix") . updateDouble(LePrix) 
. Col umns.getByName ("Intitule") . updateString(LeLi belle) 
. Col umns . getByName ("Stock") . updatelnt (EnStock) 
' la colonne Ref est auto-i ncrementee 
.insertRow ' inserer 1 ' enregi strement dans la table 
.dispose ' detruire le RowSet 
End Sub 

Modifier ou supprimer un enregistrement d'une table 

La modification et la suppression d'un enregistrement present dans une table ne 
posent pas non plus de difficulte particuliere. II suffit de reprendre les methodes 
employees avec le ResultSet. Reportez-vous aux exemples de la bibliotheque 
avecRowSet du document Codel2-01.odt du Zip telechargeable. 

Tri et filtre supplementaires 

Vous pouvez effectuer un tri, ou un filtre, ou les deux, sur le resultat de la commande. 
Le ResultSet obtenu en tiendra compte. Les fonctions de tri et de filtre dans une 
grille de formulaire utilisent ces mecanismes pour varier les affichages d'une meme 
commande SQL. 

Le tri emploie la propriete Order, de type String. Elle contient les arguments qui 
suivent habituellement un ORDER BY du langage SQL. 

Le filtre utilise la propriete Fi 1 ter du RowSet, qui contient les arguments qui suivent 
habituellement un WHERE du langage SQL. Lutilisation du filtre est validee en affec- 
tant la valeur True a la propriete Appl yFi 1 ter. 

Lexemple qui suit recherche dans la table Produits les elements dont le prix se situe 
hors d'une plage de valeurs, et trie les resultats par ordre alphabetique inverse. En ne 
gardant que les instructions correspondantes, vous pouvez vous limiter au tri ou au filtre. 

rem Codel2-01 . odt bibli : avecRowSet Module7 
Option Explicit 
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Sub Tri erFi 1 trerResul tat2 () ' ***** base embarquee BDDint 
Dim unRowSet As Object, resu As String 

unRowSet = createUnoService("com. sun. star. sdb.RowSet") 
With unRowSet 

.DataSourceName = "BDDint" 

.CommandType = com . sun . star . sdb . CommandType .TABLE 
.Command = "Produits" 

.Order = "Intitule DESC" ' trier en ordre alphabetique inverse 
.Filter = "Prix < 10.5 AND Prix > 1" 
.ApplyFilter = True 

.execute ' effectuer la requete implicite 

resu = "" 

Do While .next 

resu = resu & . Col umns . getByName("Inti tul e") . Stri ng 
& " : " & . Columns. getByName("Prix") .String & chr(13) 

Loop 

.dispose ' detruire le RowSet 

MsgBox(resu ,0, "Produits correspondants") 
End With 
End Sub 

Un tri en ordre croissant s'ecrirait : 
.Order = "Intitule" 

ou encore : 

.Order = "Intitule ASC" 

Plusieurs criteres de tris simultanes sont acceptes. Par exemple, sur la table Clients, 
voici comment classer les resultats par ordre alphabetique des noms, ordre alphabe- 
tique des prenoms en cas de meme nom, et ordre inverse du numero de clients au cas 
oil des noms et prenoms seraient identiques : 

.Order = "Nom, Prenom, NumClient DESC" 

Pour flitter une colonne numerique, les operateurs de comparaison habituels (les 
memes que pour Basic) sont utilisables. Pour une colonne texte, outre ces operateurs 
qui s'appliquent sur l'ordre alphabetique, nous disposons aussi d'une recherche gene- 
rique. Le filtre suivant recherche tous les libelles commencant par « Dent » : 

.Filter = "Intitule LIKE 'Dent%'" 
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Celui-ci recherche les liberies ne commencant pas par « Dent » : 
.Filter = "Intitule NOT LIKE 'Dent%'" 

D'autres possibilites existent selon les pilotes, consultez un manuel de langage SQL. 

Utiliser les requetes pre-enregistrees 

Nous avons vu que CommandType permet d'associer une requete pre-enregistree a un 
RowSet. Nous utiliserons la requete enregistree creee au debut de ce chapitre. 

rem Codel2-01 . odt bibli : avecRowSet Module8 
Option Explicit 

Sub UtiliserRequeteEnregistree2() 1 ***** base embarquee BDDint 
Dim unRowSet As Object, ligne As String 

unRowSet = createllnoServi ce("com . sun . star . sdb . RowSet") 
With unRowSet 

.DataSourceName = "BDDint" 

.CommandType = com. sun. star. sdb. CommandType. QUERY 

.Command = "Clients jeunes" 

.execute ' effectuer la requete enregistree 

Do 

if not .next then Exit Do 1 sortir si plus de resultat 
' colonnes resultat : Naissance, Norn, Prenom 

ligne = "Norn = " & .Columns(l) .String & " Ne en " & .Columns(O) .Int 
Loop Until MsgBox(l i gne , 1) = 2 ' sortir si on clique Annul er 
.dispose ' detruire le RowSet 

End With 

End Sub 



Les evenements du RowSet 

En complement de la manipulation des enregistrements, l'objet RowSet engendre des 
evenements permettant un controle fin des actions. Le principe des gestionnaires 
d'evenements, ou Listener, est expose au chapitre 14. 

Ces evenements peuvent etre intercepted au moyen de Listener a deux niveaux : 

• avant Taction, pour approbation {approve en anglais), avec le service 
com . sun . star . sdb .XRowSetApproveLi stener ; 

• apres Faction grace a com. sun. star. sdbc.XRowSetListener. 
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Ces deux Listener sont affectes au RowSet respectivement par les methodes 
addRowSetApproveLi stener et addRowSetLi stener. L'exemple suivant est interessant 
a executer pas a pas dans l'EDI, en cliquant sur le bouton Etape de procedure. 

rem Codel2-01.odt bibli : avecRowSet ModuleEvt 
Option Explicit 

Sub IntercepterEvenementslO ' ***** base dBase BDDext 

Dim unRowSet As Object, ecoutel As Object, ecoute2 As Object 

unRowSet = createUnoService("com. sun. star. sdb. RowSet") 
With unRowSet 

1 mise en place des ecoutes 

ecoutel = createUnoLi stener("ecouteAvant_" , _ 

"com . sun . star . sdb .XRowSetApproveLi stener") 
.addRowSetApproveLi stener (ecoutel) 

ecoute2 = createUnoLi stener("ecouteApres_" , _ 
"com . sun . star . sdbc . XRowSetLi stener") 
.addRowSetListener(ecoute2) 

' travail sur le RowSet 

.DataSourceName = "BDDext" 

.CommandType = com . sun . star . sdb . CommandType .TABLE 
.Command = "Clients" 
. execute 

' colonnes resultat : REF, NOM, PRENOM, NAISS 
.next ' premier resultat 
.next ' deuxieme resultat 

MsgBox("Modification de " & .getString(2) & " " & .getString(3)) 

. updateStri ng(3 , "Claudine") ' changer le prenom 

. updateRow 

. moveToInsertRow 

.updatelnt(l, 50) 

. updateStri ng(2 , "Allezi") 

. updateStri ng(3 , "Lola") 

.updatelnt(4, 1990) 

.insertRow ' ajouter cet enregi strement 

.execute ' recharger le RowSet => evenement RowSetChange 

.last 

' supprimer les ecoutes 

. removeRowSetApproveLi stener (ecoutel) 

. removeRowSetListener(ecoute2) 

.dispose ' detruire le RowSet 
End With 
End Sub 



' gestionnai res des evenements XRowSetApproveLi stener - 
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Function ecouteAvant_approveCursorMove(eve As Object) As Boolean 
dim rep As Long 

rep = Msgbox("Passer a une autre "ligne ?",4) 
ecouteAvant_approveCursorMove = (rep = 6) 
End Function 

Function ecouteAvant_approveRowChange(eve As Object) As Boolean 
dim rep As Long 

rep = MsgBox("Modi fi er la ligne ?", 4) 
ecouteAvant_approveRowChange = (rep = 6) 
End Function 

Function ecouteAvant_approveRowSetChange(eve As Object) _ 

As Boolean 

MsgBox("Le RowSet va changer") 
ecouteAvant_approveRowSetChange=true 
End Function 

Sub ecouteAvant_disposing() ' necessaire, meme si pas utilise 
End Sub 

' gesti onnai res des evenements XRowSetLi stener 

Sub ecouteApres_cursorMoved(eve As Object) 
MsgBox "On est passe a un autre ligne" 
End Sub 

Sub ecouteApres_rowChanged(eve As Object) 
MsgBox "La ligne vient d'etre modifiee" 
End Sub 

Sub ecouteApres_rowSetChanged(eve As Object) 
MsgBox "Le RowSet vient de changer" 
End Sub 

Sub ecouteApres_disposing() ' necessaire, meme si pas utilise 
End Sub 

Apres avoir obtenu un objet RowSet, nous nous en servons pour mettre en place l'inter- 
ception d' evenements. Ici, nous traitons les deux jeux d'evenements, mais nous pour- 
rions nous limiter par exemple aux evenements d'approbation. Le premier argument de 
createUnoLi stener est le prefrxe qui sera utilise pour chaque routine de gestion des 
evenements concernes. Le prefrxe doit se terminer par le caractere « souligne ». 

Pour chaque service d'evenements intercepte, chacun d'eux doit etre traite par un 
sous-programme Sub ou Function, y compris l'evenement disposing qui existe tou- 
jours, et pour lequel on ne fait souvent rien de particulier. Chaque routine d'intercep- 
tion recoit en argument optionnel un objet evenement. Les routines d'approbation 
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sont des fonctions booleennes qui doivent renvoyer True pour approuver l'evene- 
ment, Fal se pour l'annuler. 

Dans la sequence de travail avec le RowSet, nous avons mis en gras les instructions 
qui vont declencher des evenements (avant, apres). 

Le traitement des Listener est tres important dans la validation des donnees a entrer 
ou pour controler l'execution de votre code. Nous verrons au chapitre 13 que les for- 
mulaires donnent un acces simplifie a ces evenements. 



Les transactions 

Tout au long de 1' expose precedent, nous avons pu constater que toute modification 
sur la base de donnees intervenait immediatement. II est cependant des cas ou des 
traitements longs faisant intervenir plusieurs requetes successives sont a valider glo- 
balement. C'est la notion de transaction. 

Le pilote de base de donnees dBase utilise par notre base de donnees BDDext ne 
permet pas les transactions. Le pilote de la base embarquee BDDint supporte en 
partie les mecanismes de transactions, car il est une adaptation de HSQLDB, mais il 
ne detecte pas les conflits. Pour votre projet assurez-vous que votre base de donnees 
externe supporte bien les transactions. 

Ouverture de la base 

Le mecanisme de transaction est gere par la connexion qui supervise les modifica- 
tions de contenu de la base afin d'eviter les conflits. Si on utilise un RowSet, il devra 
utiliser une connexion etablie pour la transaction. Dans l'exemple suivant, nous eta- 
blissons une connexion pour transaction et affichons la valeur initiale du niveau 
d'isolement de la transaction. 

rem Codel2-01.odt bibli : Transactions Modulel 
Option Explicit 

Sub TransactionParDefautO 
Dim maConnexion As Object 

maConnexion = ConnecterSourcePourTransaction("BDDi nt") ' essayez BDDext 
afficherNiveauIsol ement (maConnexion) 
DeconnecterSource (maConnexion) 
End Sub 
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Function ConnecterSourcePourTransactiori(nomSource As String, 
Optional nomUtilisateur As String, _ 
Optional motDePasse As String) As Object 

Dim maSource As Object, dbContexte As Object 
if IsMi ssi ng(nomUti 1 i sateur) then 

nomUtilisateur = "" 

motDePasse = "" 
elseif IsMi ssi ng(motDePasse) then 

motDePasse = "" 
end if 

dbContexte = CreateUnoServi ce("com . sun . star . sdb . DatabaseContext") 
if dbContexte . hasByName(nomSource) then 

maSource=dbContexte. getByName(nomSource) 

ConnecterSourcePourTransaction = 

maSou rce . getlsol atedConnection (nomUti 1 i sateu r , motDePasse) 

end if 

End Function 



Sub afficherNiveauIsolement(maConnexion As Object) 
Dim mess As String 

mess = "Validation immediate ? " & maConnexion . AutoCommit & chr(13) 
Select Case maConnexion.Transactionlsolation 
Case com . sun . star . sdbc .Transacti onlsol ati on . NONE 

mess = mess & "Methode utilisee : NONE" 
Case com . sun . star . sdbc .Transacti onlsol ati on . READ UNCOMMITTED 

mess = mess & "Methode utilisee : READ_UNCOMMITTED" 
Case com . sun . star . sdbc .Transacti onlsol ati on . READ COMMITTED 

mess = mess & "Methode utilisee : READ_COMMITTED" 
Case com . sun . star . sdbc .Transacti onlsol ati on . REPEATABLE_READ 

mess = mess & "Methode utilisee : REPEATABLE_READ" 
Case com . sun . star . sdbc .Transacti onlsol ati on . SERIALIZABLE 

mess = mess & "Methode utilisee : SERIALIZABLE" 
End Select 

MsgBox(mess, 0, "Niveau d ' i sol ement") 
End Sub 

L'etablissement de la connexion fait appel a la methode getlsol atedConnection. Par 
defaut, les connexions valident les modifications des l'instruction soumise par une 
instruction execute. C'est la propriete autoCommit qui indique ce comportement 
avec la valeur True. Si nous desirons entrer dans un processus de transaction, il nous 
faudra modifier ce comportement par defaut pour informer la connexion quelle doit 
attendre un ordre explicite avant d'inscrire definitivement les modifications en base. 

Le sous-programme afficherNi veaulsol ement donne une information supplemen- 
taire, que nous allons expliciter. Lorsque deux transactions (sur des processus inde- 
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pendants) travaillent sur la meme zone de table, se pose le probleme de Faeces con- 
current aux donnees. Plusieurs anomalies peuvent se produire : 

• La transaction 1 modifie une ligne, mais avant que cette modification soit validee 
par commi t, la transaction 2 lit cette ligne : si la transaction 1 est annulee par 
rol 1 back, la donnee lue par la transaction 2 est inexacte. Cette situation est appe- 
lee dirty read (lecture sale). 

• La transaction 1 lit une ligne, la transaction 2 modifie cette ligne, puis la 
transaction 1 relit la ligne : la premiere lecture est differente de la deuxieme. Cette 
situation est appelee non-repeatable read (lecture non repetitive). 

• La transaction 1 recupere une serie de lignes satisfaisant a une condition WHERE, la 
transaction 2 ajoute une ligne qui satisfait aussi a la condition WHERE, puis la 
transaction 1 relance la meme condition WHERE et recupere une ligne nouvelle 
(ligne fantome). Cette situation est appelee phantom (fantome). 

II est possible d'indiquer a une connexion de transaction comment gerer faeces con- 
current, en modifiant le contenu de la propriete Transact! onlsolati on si le moteur 
de la base de donnees le permet. Les valeurs possibles, listees dans le tableau 12-11, 
sont des constantes nominees de la forme : 

I com . sun . star . sdbc .Transact! onlsol ati on . NONE 



Tableau 12-11 Constantes de Transactionlsolation 



Constante Description 


NONE 


Les transactions ne sont pas prises en charge. 


READ_UNCOMMITTED 


Les lectures peuvent produire des dirty reads, non-repeatable reads, et phantoms. 


READ_COMMITTED 


Seuls les dirty reads sont empeches. 


R EA P EATAB L E_R E AD 


Les dirty reads et non-repeatable reads sont empeches, mais pas les phantoms. 


SERIALIZABLE 


Les dirty reads, non-repeatable reads, et phantoms sont empeches. La conse- 
quence est que les demandes de transaction sont satisfaites successivement 
(e'est-a-dire en serie). 



Gerer les transactions 

Afin d'illustrer l'utilisation des transactions, nous presentons un exemple certes sim- 
pliste mais particulierement eloquent : nous modifions un enregistrement, inserons 
un autre, et demandons la confirmation de la transaction. Les transactions s'appli- 
quent bien entendu a des cas beaucoup plus complexes, et la aussi il faut etudier soi- 
gneusement les traitements d'erreur d'execution. Rappelons que la base embarquee 
utilisee pour l'exemple ne detecte pas les conflits de transactions. 
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rem Codel2-01.odt bibli : Transactions Module2 
Option Explicit 

Sub TestTransactionO ' ***** base embarquee BDDint 
Dim maConnexion As Object, unRowSet As Object 

surveill erTabl e("Cl i ents" , "Etat initial") 
maConnexion = ConnecterSourcePourTransaction("BDDint") 
maConnexion . AutoCommit = False' on ouvre la transaction 
af f icherNiveauIsol ement (maConnexi on) 

UnRowSet = createUnoServi ce("com . sun . star . sdb . RowSet") 
With unRowSet 

.activeConnection = maConnexion 

.CommandType = com. sun. star. sdb. CommandType. TABLE 
.Command = "Clients" 
. execute 

if .absolute(2) then ' modifier un enregi strement 

.Col umns . getByName("Prenom") . updateSt ring ("Valerie-Anne") 
. updateRow 

end if 

' ajouter un nouvel enregi strement 

. moveToInsertRow ' aller a la zone de preparation 

. Col umns . getByName("Nom") . updateSt ri ng("Cepamoi ") 

. Col umns . getByName("Prenom") . updateSt ri ng("Jean-Edouard") 

. Col umns . getByName("Nai ssance") . updatelnt(1988) 

1 la colonne Ref est auto-i ncrementee 

.insertRow ' inserer 1 ' enregi strement dans la table 

surveillerTable("Clients" , "Apres insertion") 

if MsgBox("Confi rmez-vous les changements ?", 48+4) = 6 then 

maConnexi on . commit ' OUI 
el se 

maConnexion. rollback' NON 
endi f 

.dispose ' detruire le RowSet 
End With 

maConnexion .AutoCommit = True' fermer la transaction 
DeconnecterSource (maConnexi on) 
surveillerTable("Clients" , "Etat final") 
End Sub 



Sub surveillerTable(nomTabl e As String, titre As String) 
Dim unRowSet As Object, message As String 

unRowSet = createUnoServi ce("com . sun . star . sdb . RowSet") 
With unRowSet 

.DataSourceName = "BDDint" 

.CommandType = com . sun . star . sdb . CommandType .TABLE 
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.Command = nomTable 
. execute 

if . absol ute(2) then ' lire 1 ' enregi strement en modification 
message = chr(13) & "Enregi strement 2 :" & chr(13) & _ 

. Columns. getByName("Nom") .String & " " & _ 

. Col umns . getByName("Prenom") . Stri ng & chr(13) 
end if 

.afterLast ' aller au-dela du dernier enregi strement 
if . IsRowCountFi nal then 

message ="Nombre d 1 enregi strements : " & .RowCount & message 
el se 

message = "Erreur, fin de table pas atteinte !" 
end if 

MsgBox(message , 0, titre) 

.dispose ' detruire le RowSet et sa connexion 
End With 
End Sub 

Nous utilisons un sous-programme surveillerTable qui nous permet de visualiser 
un enregistrement particulier et le nombre total d'enregistrements. Ce sous-pro- 
gramme utilise un RowSet qui cree sa propre connexion a la base BDDi nt. 

Nous ouvrons done une connexion dans le mode transactionnel et desactivons le 
mode de validation automatique. Puis, nous affichons le niveau d'isolement avec le 
sous-programme de l'exemple precedent. Nous utilisons un RowSet pour effectuer la 
transaction. II est greffe sur cette connexion. Nous modifions le deuxieme enregistre- 
ment (une facilite, pour l'exemple), et ajoutons un nouvel enregistrement. Le sous- 
programme survei 1 1 erTabl e affiche bien ce nouvel etat de la base, transitoire. 

La macro demande done ensuite d'accepter ces changements. Si l'utilisateur repond 
oui alors la transaction est validee par la methode commi t. Si l'utilisateur repond non, 
toute la transaction est annulee par la methode rol 1 back. 

Nous fermons alors la transaction en replacant la connexion dans son mode par defaut 
de validation automatique. Le sous-programme survei 1 1 erTabl e confirme l'etat final 
de la table : soit les deux changements ont eu lieu, soit aucun ha ete conserve. 



Utilisation dans le contexte bureautique 

OpenOffice.org n'est pas qu'un gestionnaire de bases de donnees et l'interet de l'API 
sur les bases de donnees est de pouvoir utiliser ces fonctionnalites dans un contexte 
bureautique. Nous presentons maintenant quelques exemples non exhaustifs des trai- 
tements possibles. 
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Le publipostage 

Une utilisation frequente des sources de donnees en bureautique est le publipostage. 
II permet par exemple de remplir une lettre type avec des informations propres a 
chaque enregistrement de la source de donnees. A titre d'exemple, nous allons effec- 
tuer un publipostage sur la table Clients de notre source de tests BDDext. La lettre 
type aura ete preparee auparavant a l'aide de l'outil mailing du traitement de texte. 
Nous utiliserons le fichier annonceSoldes .odt, fourni dans le Zip telechargeable. 
Nous allons creer autant de fichiers textes qu'il y a de clients dans la base de donnees. 
Chaque fichier comporte les nom, prenom et adresse du client. 

rem Codel2-01 . odt bibli : Publipostage Modulel 
Option Explicit 

Sub PublipostageFichiersO 

Dim nomSource As String, nomTable As String, col onnePref i xe As String 

Dim URLmodele As String, repResultats As String 

Dim monPubli postage As Object, props() 

nomSource = "BDDext" 
nomTable = "Clients" 
colonnePrefixe = "NOM" 

URLmodele = ConvertTollRL("C:\Docs OpenOff i ce\annonceSol des . odt") 
repResultats = ConvertToURL("C:\Docs OpenOffi ce\resul tat\") 

monPubl i postage = createUnoServi ce("com . sun . star . text . Mail Merge") 
With monPubli postage 

. DataSourceName = nomSource 

.CommandType = com . sun . star . sdb . CommandType .TABLE 
.Command = nomTable 

.OutputType = com. sun. star. text. Mail Me rgeType. FILE 
. FileNameFromColumn = True 
.FilenamePrefix = colonnePrefixe 
' . SaveAsSi ngl eFi 1 e = True 

' .SaveFilter = "wri ter_pdf_Export" ' exemple d' export en PDF 
.DocumentURL = URLmodele 
.OutputURL = repResultats 

.execute(propsO) 'Envoi de la commande de publipostage 
End With 

MsgBox("Fin du publipostage") 
End Sub 

La fonction de publipostage est directement accessible depuis le service Mail Merge. II 
expose de nombreuses proprietes listees pele-mele dans la documentation de l'API, 
nous allons les decrire par categories. 
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Dans le tableau 12-12, on retrouve des proprietes que nous avons deja vues a propos 
du RowSet. Elles concernent Faeces a la base de donnees : DataSourceName, 
ActiveConnection, CommandType, Command. Nous nous contentons d'explorer une 
table, mais nous pourrions effectuer des recherches plus sophistiquees avec une 
requete ou une commande SQL. Une alternative est d'indiquer dans la propriete 
ResultSet un objet ResultSet ou un RowSet deja initialise, ce qui est plus efficace 
que d'utiliser le ResultSet implicite obtenu par les proprietes precedentes. Les pro- 
prietes Sel ecti on et Fi 1 ter permettent de selectionner les resultats utiles. Attention, 
la selection semble ne pas fonctionner (Issue 50519, Issue 62958). 



Tableau 12-12 Proprietes concernant I'interrogation de la base de donnees 



Propriete 


Type 


Signification 


DataSourceName 


Stri ng 


Nom de la source de donnees. 


Acti veConnecti on 


Object 


Connexion vers la base de donnees. 


ResultSet 


Object 


Optionnel : un ResultSet existant, a utiliser pour interroger la 
base de donnees. 


CommandType 


Long 


Voir le tableau 12-10. 


Command 


Stri ng 


Voir le tableau 12-10. 


Selection 


□ Object 


Tableau de bookmarks sur le Resul tSet 


EscapeProcessi ng 


Boolean 


True pour eviter que la commande SQL ne soit analysee par 
OpenOffice avant son envoi au moteur de base de donnees. 


Filter 


Stri ng 


Filtre eventuel sur les resultats. II faut utiliser la meme syntaxe 
qu'apres le WHERE d'une instruction SQL. 



La propriete DocumentURL sert a indiquer l'adresse du document servant de modele. 
La propriete OutputType permet de specifier un des trois modes de sortie possibles, 
avec une constante nommee : 



com. sun . star . text . Mai lMergeType . FILE ' sortie sous forme de fichiers 
com. sun . star . text . Mai lMergeType . PRINTER' sortie sur une imprimante 
com. sun . star . text . Mai lMergeType . MAIL ' sortie sous forme de courriels 

Dans notre exemple, nous voulons une sortie de fichiers. On indique dans quel reper- 
toire stocker les fichiers crees, et comment les nommer (voir le tableau 12-13). Un 
moyen simple de nommer ces fichiers est d'utiliser comme prefixe une des colonnes du 
resultat. En executant l'exemple avec notre base BDDext, vous constaterez que les 
fichiers commencent par le nom du client suivi d'un numero : si le fichier existe deja 
dans le repertoire, un autre numero est utilise, ce qui est le cas pour les deux clients 
Durand. Si les proprietes Fi 1 eNameFromCol umn et Fi 1 enamePref i x ne sont pas initiali- 
sees, les fichiers utilisent comme prefixe le nom du fichier modele. La propriete 
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SaveAsSingleFile permet d'obtenir un seul fichier contenant toutes les lettres, cha- 
cune separee par un saut de page. Ceci est bien pratique pour imprimer l'ensemble. 



Tableau 12-13 Proprietes concemant une sortie fichier 





OutputURL 


Stri ng 


Repertoire oil seront crees les fichiers. 


Fi 1 eNameFromCol umn 


Bool ean 


True si les noms de fichiers proviennent d'une colonne de la 
base de donnees. 


Fi 1 eNamePref i x 


String 


Norn de la colonne servant a creer les noms de fichier. 


SaveAsSi ngl eFi 1 e 


Bool ean 


True pour regrouper les resultats dans un seul fichier. 


SaveFilter 


String 


Nom du filtre d'export pour les fichiers obtenus. Voir I'export 
de fichiers, chapitre 7. 


SaveFilterData 


□ Object 


Parametres eventuels du filtre (tableau de structures 
PropertyVal ue). 


SaveFi 1 terOpti ons 


String 


Parametres eventuels du filtre. 



Les proprietes SaveFilter. . . permettent de convertir (ou d'exporter) le document 
dans un autre format que le format du modele et correspondent aux proprietes simi- 
laires FilterName, etc., decrites au chapitre 7. La pseudo-propriete SaveFilterData 
ne fonctionne pas directement avec Basic, on doit utiliser la methode 
setPropertyVal ue. 



monPubl i postage . setPropertyVal ue("SaveFil terData" , optsFi ltre() ) 

II ne reste plus qua lancer le publipostage avec la methode execute, qui utilise un 
tableau de proprietes. Ici, un tableau vide suffit car nous avons rempli directement 
chaque propriete. On aurait pu les transmettre dans ce tableau, mais cette methode 
est davantage sujette a erreurs. 



Sortie imprimante 

Pour imprimer directement le resultat, la propriete OutputType doit avoir la valeur 
PRINTER. A la place des proprietes de sortie fichier, on utilise deux autres proprietes : 
• La propriete SinglePrintJobs evite d'envoyer une multitude de travaux (en 
anglais jobs) a l'imprimante. Le nom de cette propriete est trompeur, car il faut 
employer la valeur False (c'est-a-dire la valeur par defaut) pour regrouper les 
resultats dans un seul envoi a 1'imprimante. 
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• La propriete Pri ntOptions sert a transmettre les options d'impression vues au 
chapitre 7, a la section « Lancer l'impression ». A cause d'un bogue, on doit utili- 
ser en Basic la methode setPropertyValue pour la remplir : 

monPubli postage. setPropertyVal ue("PrintOptions" , printOptsO ) 

Sortie courriel 

Si la propriete OutputType prend la valeur MAIL, le resultat du publipostage sera une 
serie de courriers electroniques. Pour que le publipostage fonctionne, il faut remplir 
les informations du panneau Outils>0ptions>0pen0ffice.org Writer>E-mail de mailing. 
Utilisez le bouton Tester les parametres pour verifier les parametres du compte de votre 
messagerie. 

Ce type de publipostage utilise aussi des proprietes specifiques, comme le montre le 
tableau 12-14. La propriete OutputURL doit etre remplie, bien que le repertoire 
indique ne semble pas utilise. Dans notre exemple, pour changer un peu, nous utili- 
sons une requete qui recupere les clients ayant donne leur adresse e-mail. Notez que 
dans nos essais, le fichier attache etait recu vide, ou 1' application OpenOffice.org 
bloquait. II s'agit sans doute de quelques bogues residuels... 

rem Codel2-01.odt bibli : Publipostage Module3 
Option Explicit 

Sub Publ i postageCourriel () 

Dim nomSource As String, URLmodele As String, repResultats As String 
Dim monPubl i postage As Object, props() 
nomSource = "BDDext" 

repResultats = ConvertToURL("C : \Docs OpenOffi ce\resultat\") 

monPubl i postage = createUnoServi ce("com . sun . star . text . Mai 1 Merge") 
With monPubl i postage 

.DataSourceName = nomSource 

.CommandType = com. sun. star. sdb . CommandType . QUERY 

.Command = "Clients avec courriel" 

.OutputType = com. sun . star . text . Mai lMergeType . MAIL 

.OutServerPassword = "" 

.InServerPassword = "" 

.AddressFromColumn = "EMAIL" 

. SendAsAttachment = True 

.Subject = "Sol des ! Sol des ! Sol des !" 

.Mail Body = "Lisez vite le document ci -joint !" 

. AttachmentName = "Annonce" 

.AttachmentFilter = "wri ter_pdf_Export" ' exemple d'export en PDF 
.DocumentURL = URLmodele 
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.OutputURL = repResultats 

.execute(propsO) 'Envoi de la commande de publ i postage 
End With 

MsgBox("Fin du publ i postage") 
End Sub 



Tableau 12-14 Proprietes concernant une sortie courriel 



Propriete 


Type 


Signification 


OutServerPas sword 


Stri ng 


Mot de passe eventuellement necessaire pour acceder au serveur 
de courrier sortant. 


InServer Password 


Stri ng 


Mot de passe eventuellement necessaire pour acceder au serveur 
de courrier sortant, dans le cas d'un serveur de courrier configure 
en authentication « SMTP apres POP». 


OutputURL 


Stri ng 


Repertoire ou seront crees les fichiers. 


Subject 


Stri ng 


Sujet du courriel. 


AddressFromCol umn 


Stri ng 


Nom de la colonne servant a obtenir I'adresse de courrier elec- 
tronique du destinataire. 


SendAsAttachment 


Boolean 


True pour envoyer le document en piece attachee. 


SendAsHTML 


Boolean 


True pour envoyer le document en format HTML dans le corps 
du message. 

Pris en compte si SendAsAttachment a la valeur Fal se. 


Mai 1 Body 


Stri ng 


Texte du corps du message. 

Pris en compte si SendAsAttachment a la valeur True. 


AttachmentName 


Stri ng 


Nom de la piece attachee. 

Pris en compte si SendAsAttachment a la valeur True. 


AttachmentFilter 


Stri ng 


Nom du filtre d'export pour les fichiers obtenus. Voir I'export de 
fichiers, au chapitre 7. 

Pris en compte si SendAsAttachment a la valeur True. 


Copi esTo 


[] String 


Tableau de chames de caracteres contenant les adresses de cour- 
riel en copie visible. 


BlindCopiesTo 


[] String 


Tableau de chames de caracteres contenant les adresses de cour- 
riel en copie cachee. 



Calc et les bases de donnees 

Dans cette section, nous utiliserons Calc en tant que classeur, et non comme base de 
donnees. Calc est a meme d'utiliser des donnees provenant d'une base de donnees 
quelconque, pour creer des graphes, par exemple. 
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Importer des donnees dans Calc 

Nous allons importer dans une feuille de tableur le resultat d'une requete sur la base 
BDDi nt. 

rem Codel2-02 . ods bibli : Standard Modulel 
Option Explicit 

Sub ImporterDepui sUneBase() 

Dim monDocument As Object, maFeuille As Object, propsBDD As Variant 

Dim coi nResul tats As Object, zoneResul tats As Object 

Dim zonesBDD As Object, maZoneBDD As Object, nomMaZone As String 

nomMaZone = "Ados" 
monDocument = Thi sComponent 

maFeuille = monDocument . Sheets . getByName("RecupBDD") 
coi nResul tats = maFeui 1 1 e . getCel 1 RangeByName("C2") 

zonesBDD = monDocument . DatabaseRanges 

if zonesBDD . hasByName(nomMaZone) then zonesBDD. removeByName(nomMaZone) 
zonesBDD . addNewByName(nomMaZone , coi nResul tats . RangeAddress) 

propsBDD = CreateProperties(Array( _ 
"DatabaseName" , "BDDint", 

"SourceType" , com . sun . star . sheet . DatalmportMode .QUERY, _ 
"SourceObject" , "Clients jeunes" )) 

coi nResul tats . dolmport (propsBDD) 
maZoneBDD = zonesBDD. getByName (nomMaZone) 
zoneResul tats = maZoneBDD. Refer redCel Is 
zoneResul tats. Cell BackCol or = RGB(255, 255, 200) 
End Sub 

Le tableur memorise dans la propriete DatabaseRanges chacune des zones servant a 
une importation de donnees. Calc est capable de creer une telle zone a la volee lors 
d'une action d'importation, mais nous preferons declarer explicitement la zone de 
reception. L'objet obtenu de DatabaseRanges est une collection d'objets nommes : 
chaque zone de reception existant dans le document possede un nom. La methode 
hasByName renvoie True si le nom est deja pris par une zone existante. Dans ce cas, la 
methode removeByName permet de la supprimer de la collection. On declare la nou- 
velle zone par la methode addNewByName, avec en argument le nouveau nom et les 
coordonnees de la cellule du coin haut-gauche de la zone de reception. Ainsi, les 
donnees seront ecrites dans une table debutant a cette position. 

Limportation des donnees est effectuee par la methode dolmport de la cellule du 
coin de la zone de reception. Cette methode necessite en argument un tableau de 
structures PropertyValue dont les proprietes (voir le tableau 12-15) proviennent du 
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service com. sun. star. sheet. DatabaselmportDescri ptor. Pour remplir facilement 
ce tableau, nous utilisons la routine utilitaire CreateProperties, decrite a 1' annexe B. 

Tableau 12-15 Descripteur d'importation de donnees 



Propriete 


Type 


Signification 


DataBaseName 


Stri ng 


Norn de la source de donnees. 


SourceType 


Long 


Voir le tableau 12-16. 


SourceObject 


Stri ng 


Voir le tableau 12-10. 


IsNati ve 


Bool ean 


True pour eviter que la commande SQL ne soit analysee par OpenOf- 
fice avant son envoi au moteur de base de donnees. 



Les constantes nominees de la propriete SourceType (voir le tableau 12-16) condi- 
tionnent le contenu de SourceObject. Elles sont de la forme : 

com . sun . star . sheet . DatalmportMode . NONE 



Tableau 12-16 Valeurs possibles de SourceType 




NONE 


Aucune importation n'est effectuee. 


SQL 


La source de l'importation est une requete SQL. 


TABLE 


La source de l'importation est une table. 


QUERY 


La source de l'importation est une requete enregistree. 



Une fois l'import effectue, l'objet zone de reception maZoneBDD nous donne, par sa 
propriete ReferredCell s, un objet zone de cellules couvrant exactement toutes les 
donnees importees. Nous nous en servons ici pour colorer en jaune pale le fond de 
ces cellules. La propriete DataArea de l'objet maZoneBDD fournit une structure 
Cell RangeAddress qui permet egalement de determiner les coordonnees de la zone 
de cellules (voir le chapitre 9). 

Si la base de donnees est modifiee par d'autres processus (par exemple une base four- 
nissant des cours de Bourse en temps reel), il est possible de rafraichir les donnees 
importees, soit sur demande avec la methode refresh, soit periodiquement avec la 
propriete Ref reshPeriod. 



I 



maZoneBDD. Ref reshPeriod = 30 ' rafraichir toutes les 30 secondes 



Le service com. sun. star. sheet. DatabaseRange et son interface XDatabaseRange 
disponibles sur l'objet maZoneBDD comportent d'autres possibilites, dont un filtrage, 
un tri et une sous-totalisation. Nous ne nous etendrons pas dessus, consultez la docu- 
mentation API du service et suivez les nombreux liens. 
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Une requete dans une cellule 

Le fichier CalcSQL.ods regroupe quelques fonctions permettant d'acceder aux 
sources de donnees depuis Calc. Sans dormer le detail de tout le code, nous en men- 
tionnerons les points importants. 

Ces fonctions s'appuient sur le fait qu'une macro, definie sous forme de fonction, 
peut etre appelee depuis une cellule de Calc. Bien que n'apparaissant pas dans 
l'Autopilote, le resultat retourne par la fonction, sous forme matricielle ou non, sera 
affiche dans Calc au meme titre qu'une fonction intrinseque. 

Une formule matricielle s'obtient en validant la saisie de la fonction dans Calc par 
Ctrl + Maj + Entree a la place de la seule touche Entree. Du cote de la macro, ce retour 
matriciel se traduit par un resultat sous forme de tableau. Une premiere approche 
consiste a exploiter directement l'API d'acces aux sources de donnees avec laquelle 
nous avons deja travaille. Void a quoi pourrait ressembler l'appel depuis une cellule 
Calc (la ligne est coupee en deux par la mise en page). 

=CALCSQLl("SourceDeDonnees" ; "select * from LaTable 
where LeChamp=" & Apos(A14)) 

On remarque que les arguments sont separes par des points-virgules et que la conca- 
tenation de chaines est autorisee par l'intermediaire de l'operateur &. Si necessaire, 
n'hesitez pas a utiliser la fonction Apos. Cette syntaxe permet l'utilisation de valeurs 
issues d'autres cellules pour construire la requete, par exemple A14. 

La fonction CalcSQLl contient plusieurs arguments, certains obligatoires, d'autres 
optionnels, comme le montre le tableau 12-17. 

Tableau 12-17 Arguments de la fonction CalcSQLl 



1 


nomSource Non 


Nom de la source de donnees telle que definie dans Ooo - La casse 
est importante 


2 


Requete 


Non 


Requete SQL valide de type SELECT. Aucun controle de validite 
autre que celui interne a OpenOffice.org n'est effectue. 


3 


AfficheTitre 


Oui 


La valeur 1 permet d'afficher le nom des colonnes recuperees. 


4 


BorneMax 


Oui 


Affiche les BorneMax premiers elements. 


5 


BorneMin 


Oui 


Saute les BorneMi n premiers elements. 
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Ces arguments de la formule Calc sont en fait les arguments de la macro. II est 
cependant a noter que les parametres optionnels ne le sont que s'ils sont situes a la fin 
de la formule. Si ce n'est pas le cas, il deviennent obligatoires. 

Function CalcSQLlfnomSource, Requete, _ 
Optional AfficheTitre, _ 
Optional BorneMax, Optional BorneMin) 

Les traitements de cette macro sont exactement dans l'esprit des macros que nous 
avons explorees precedemment. Nous ne redetaillerons pas le processus. Une fois le 
traitement effectue, la macro retourne un tableau. 

CalcSQLl = TabResultatO 

La cellule Calc contient alors le resultat de la requete. 



Attention Resultats matriciels 

II existe plusieurs problemes dus aux retours matriciels : 

• Toutes les cellules affichees sont recalculees : cela implique des appels successifs aux fonctions qui 
peuvent etre penalisants si la requete est lourde. 

• Lorsque la fonction a ete evaluee une premiere fois, la tail le de la matrice n'est pas adaptee si Ton 
change la requete. Cela implique I'affichage de #NA si moins de lignes sont retournees. Si plus de 
lignes sont retournees, le retour est tronque a la taille initiale. 



Importer des donnees depuis une cellule 

Le tableur Calc permet, par l'intermediaire de la touche F4, d'afficher le pilote de 
sources de donnees. A partir de cet endroit, toute requete ou table glissee-deposee 
dans une feuille importe les donnees. Le lien n'est cependant pas conserve. 

La fonction Cal cSQL2 utilise l'API d'importation des donnees que nous avons prece- 
demment decrite afin de reproduire et d'automatiser ce comportement. La requete 
source est alors conservee. 

=CALCSQL2('Teui lie"; "Cellule"; "Source"; "select * from LaTable 
where LeChamp=" & Apos(A14)) 

La fonction Cal cSQL2 importe done le resultat de la requete a l'endroit specifie par 
les arguments. Le resultat est cellule par cellule et non pas matriciel. Les arguments 
de cette fonction (tableau 12-18) sont tous obligatoires. 
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Tableau 12-18 Arguments de la fonction CalcSQL2 





1 


NomFeuille 


Feuille oil sera affiche le resultat - Doit etre differente de la feuille contenant la 
cellule. 


2 


CelluleCible 


Cellule en haut a gauche contenant le resultat. 


3 


nomSource 


Nom de la source de donnees telle que definie dans Ooo. La casse est importante. 


4 


Requete 


Requete SQL valide de type SELECT. Aucun controle de validite autre que celui 
interne a OpenOffice.org n'est effectue. 



On remarque que les arguments sont separes par des points-virgules et que la conca- 
tenation de chaines est autorisee par l'intermediaire de l'operateur &. Si necessaire, 
n'hesitez pas a utiliser la fonction Apos. Cette syntaxe permet done l'utilisation de 
valeurs issues d'autres cellules pour construire la requete, par exemple A14. 

Le fichier CalcSQL.ods propose une derniere fonction Ca"lcSQL3 qui comprend 
davantage d'options de mise en forme. Cette fonction reprend les deux approches 
exposees ci-dessus, nous ne nous y attarderons done pas. 

Importer les requetes MS-Access 

Nous avons vu qu'il etait possible de creer dynamiquement des requetes enregistrees. 
Cette technique va nous permettre d'importer les requetes d'une base MS-Access. 
Ainsi, lors d'une migration de base de donnees, nous pourrons continuer a utiliser les 
requetes, parfois complexes, qui y etaient enregistrees. 

Deux macros, une en VBA pour 1' exportation et 1' autre en OOoBasic pour l'impor- 
tation en passant par un fichier texte intermediate, vont permettre de recreer ces 
requetes dans la source de donnees utilisee par OpenOffice.org. 

Rem ATTENTION , ceci est du code VBA 

Rem IT n'est pas utili sable dans OpenOffice.org 

Rem Code VBA a executer dans Access 

Sub ExporteRequetesO 

Dim mabase As database 

Set mabase = Currentdb 

Set mesdefs = mabase .QueryDefs 

Open "Resu~lt.txt" For Output As #1 

For i = 0 To mesdefs . Count - 1 

Print #1, CStr(i) + "| " 
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Print #1, mesdefs (i ) . Name 

Print #1, mesdefs (i ) .Sql 'peut etre ecrit sur plusieurs "lignes 
Print #1, "" 
Next i 

Print #1, "Ml" 
Close #1 

MsgBox "ok" 
End Sub 

Cette premiere macro VBA parcourt toutes les requetes de la base Access et les 
exporte dans un fichier texte. 

Maintenant, la macro suivante va relire ce fichier dans OpenOffice.org, en tenant 
compte des eventuels sauts de lignes inclus dans les requetes, et va les recreer dans la 
source de donnees. 

Sub ImporteRequetesO 
Dim rien as string 

oDBContext= CreateUnoServi ce("com . sun . star . sdb . DatabaseContext") 
'Norn de la source de donnees OOo 
odb=odbcontext .getbyname("EssaiMDB") 
queri es=odb . getQueryDef i ni ti ons () 

Open "C:\Result.txt" For Input As #1 

line input #1, rien 
while not eof(l) 

NomRequete="" 

requete="" 

suite="" 

'Recupere les informations Info de chaque requete 
line input #1, NomRequete 
line input #1, requete 
line input #1, suite 
while trim(suite)<>"" 

requete=requete+" "+suite 

line input #1, suite 
wend 

while trim(suite)="" 

line input #1, suite 
wend 

'Insere la requete dans la source de donnees 

UneRequete=queri es . createlnstance 

UneRequete. setPropertyVal ue ("Command" , requete) 
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if not queri es . hasByName(NomRequete) then 

'on ne peut ecrire deux requetes avec le meme nom 
queri es . InsertByName(NomRequete , UneRequete) 
endi f 
wend 

on Error goto OOoVl 

dbDoc = odb . DatabaseDocument 'erreur avant OOo 2.0 ! 
on Error Goto 0 ' supprimer le traitement d'erreur 
dbDoc. store ' sauver la requete dans le fichier .odb 
Goto LI 
OOoVl: 

Resume LI ' ignorer 1 'erreur : OOo 1.1 ou inferieur 
LI: 

on Error Goto 0 
close #1 

Msgbox "C'est Fini" 
End Sub 

Cette macro est un premier jet. En toute rigueur, il faudrait verifier que les requetes 
sont syntaxiquement correctes et ne contiennent pas d'elements etrangers a la norme 
SQL. Nous vous laissons poursuivre ce travail... 



Conclusion 

Nous venons de presenter le traitement des sources de donnees au travers de l'API. 
Les differentes actions de creation, modification ou consultation des donnees ont ete 
exposees. Quelques exemples d'utilisation dans un contexte bureautique ont permis 
d'illustrer les concepts expliques. 

Le chapitre suivant va presenter la manipulation des formulaires directement inclus 
dans les documents et qu'on peut connecter a des sources de donnees. 



13 

Les formulaires 



Le mot formulaire (en anglais, form) a trois significations dans OpenOffice.org : 

• un document de type questionnaire, comportant des zones a remplir par 
l'utilisateur ; 

• un document affichant des informations provenant d'une base de donnees ; 

• un objet logiciel auquel sont rattaches des controles visuels, et connectable a une 
base de donnees. 

Nous traiterons dans ce chapitre de ces trois aspects qui sont lies. Nous supposons 
que vous savez creer dans un document un objet formulaire et le connecter a une base 
de donnees, sans programmation. Si OpenOffice.org facilite la creation de formu- 
laires integres a un document Base, il est tout a fait possible de definir un document 
formulaire separe, ce qui a certains avantages. Nous allons utiliser comme exemples 
des documents formulaires separes, puis nous montrerons comment acceder aux for- 
mulaires integres dans un document Base. 



Attention Vocabulaire VBA 

Dans la terminologie de Microsoft, le terme formulaire designe aussi bien une boTte de dialogue (voir le 
chapitre 1 1 ), qu'un formulaire dans Access. Ce dernier correspond au concept de document formulaire lie 
a une base de donnees. 



Dans la barre d'outils Conception de formulaires, rappelons l'existence d'un bouton pour 
afficher le Navigateur de formulaires (figure 13-1). Ce dernier visualise dans une arbo- 
rescence les objets formulaires contenus dans un document, et pour chacun les con- 
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troles qui lui sont rattaches. A partir du Navigateur de formulaire, on peut creer un 
nouvel objet formulaire, lui ajouter des controles, selectionner un controle, etc. 



Figure 13-1 

Le Navigateur de formulaires 



Formulaires 
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An LabelField 
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r. 



Plus d'informations 

Consultez I'aide F1, dans I'onglet Contenu, rendez-vous a la rubrique Fonctionnalite de la base de 
donnees, et cliquez sur la sous-rubrique Base de donnees OpenOffice.org. 
Nous conseillons la lecture prealable du chapitre 1 2 traitant des sources de donnees, ainsi que du 
chapitre 1 1 sur les boTtes de dialogue : leurs controles ont bien des points communs - mais aussi des dif- 
ferences - avec les formulaires. lis ne peuvent notamment pas etre lies a une base de donnees. 
Nous utiliserons dans les exemples les sources BDDext et BDDi nt du chapitre 12. 



API Reference sur les formulaires (en anglais) 

La documentation de I'API est decrite dans le Developer's Guide, chapitre Forms. 
► http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ 
OpenOffice.org_Developers_Guide 



Acceder aux controles (Tun formulaire 

Les objets formulaires sont rattaches a une page de dessin du document. Nous avons 
vu precedemment la notion de page de dessin dans les documents Writer, Calc, 
Draw, lorsque nous avons decrit comment inserer des formes. 

Pour acceder a un controle de formulaire, nous devons suivre un jeu de piste, resume 
a la figure 13-2. 

A partir du document, nous obtenons une page de dessin : soit celle du document 
(Writer), soit celle d'une de ses feuilles (Calc, Draw, Impress). 
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Figure 13-2 

Comment retrouver 
un controle dans 
un formulaire 




! Evenement 
! sur controle 



Source 



Vue du 




controle 


Model 



Une page de dessin peut contenir un objet formulaire ou plusieurs. La propriete 
Forms de la page de dessin nous donne une collection de formulaires (collection 
eventuellement vide). Cette collection est capable de nous indiquer si un formulaire 
d'un nom donne existe, avec sa fonction hasByName, et de nous renvoyer ce formu- 
laire avec la fonction getByName. Le formulaire est lui-meme une collection, qui con- 
tient des controles. De la meme maniere, les fonctions hasByName et getByName d'un 
formulaire permettent de verifier l'existence et d'obtenir le modele d'un controle. 
Celui-ci contient l'essentiel des proprietes utiles du controle. 

Contrairement aux boites de dialogue, le modele est l'objet controle principal. II 
existe en plus un objet « vue du controle » qui gere les proprietes visibles de celui-ci. 
II n'y a pas de lien modele vers vue, car il peut y avoir plusieurs vues s'il existe plu- 
sieurs fenetres sur le meme document. Toutefois, les vues restent coherentes entre 
elles et avec le modele. Pour obtenir la vue du controle, il est necessaire de passer par 
le controleur de la fenetre courante, qui est capable de renvoyer, avec sa fonction 
getControl, la vue du modele de controle donne en argument. 

Enfin, un controle possede une forme associee, geree comme telle dans la page de 
dessin. La forme du controle possede toutes les specificites communes aux formes 
(voir le chapitre 10), par exemple son ancrage, sa position et ses dimensions. Pour la 
retrouver, il est necessaire d'examiner successivement les formes existant dans la page 
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afin de recuperer celle qui correspond bien au controle. Pour cela, nous avons realise 
une routine utilitaire que nous detaillerons. 



Formes groupees 

II est possible de grouper les formes de plusieurs controles, mais dans ce cas, la recuperation d'une forme 
est plus complexe. 



La macro ci-dessous met en ceuvre le processus decrit. Vbus remarquerez que notre 
algorithme se base sur les noms des diverses entites pour retrouver surement 1' ele- 
ment desire. II est de votre interet de choisir vous-meme ces noms, plutot que de 
laisser ceux donnes par defaut. Dans le document Calc utilise par la macro, nous 
avons mis dans la feuille Formul aires deux formulaires, appeles FM1 et FM2. Nous 
allons rechercher un controle appele Textel dans le formulaire FM1. Nous avons 
pousse le vice jusqu'a appeler Textel un autre controle du formulaire FM2. 

rem Codel3-01.ods bibli : TrouverControl es Modulel 
Option Explicit 

Sub TrouverParLesNomsO 

Dim monDocument As Object, maFeuille As Object, maPage As Object 
Dim monControleur As Object 

Dim 1 esFormul ai res As Object, unFormulaire As Object 

Dim monCtrl As Object, vueCtrl As Object, formeCtrl As Object 

monDocument = thi sComponent 

monControleur = monDocument . CurrentControl 1 er 
maFeuille = monDocument . Sheets . getByName("Formul ai res") 
maPage = maFeui 1 1 e . DrawPage 1 recuperer la page de dessin 
lesFormulai res = maPage . Forms ' la collection des formulaires 
unFormulaire = lesFormulaires.getByNameC'FMl") 
I monCtrl = unFormulaire. getByName("Textel") 
monCtrl .Text = Time ' changer le texte affiche dans ce controle 
vueCtrl = monControleur. getControl (monCtrl) 
print "Mettre la date sur le controle Text" 
vueCtrl .Text = Date 

' rechercher la forme correspondant au controle 
' attention : il existe aussi un controle Textel dans FM2 ! 
formeCtrl = Fi ndCtrlShapeByName (maPage , "FM1", "Textel") 
print "Taille :", formeCtrl . Si ze .Wi dth , formeCtrl . Si ze . Hei ght 
End Sub 

Nous recuperons dans l'ordre la feuille de Calc, la page de dessin correspondant a la 
feuille, la collection de formulaires, puis le formulaire appele FM1 et, dans celui-ci, le 
(modele de) controle appele Textel. La propriete Text de ce controle champ de texte 
correspond au texte affiche ; nous le modifions en lui affectant l'heure courante. 
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Une fois obtenue la vue du controle, nous demontrons que nous avons le bon objet 
en affichant la date a la place de l'heure, ici aussi avec la propriete Text de la vue du 
controle. La forme (dessin) du controle est obtenue grace a la fonction utilitaire 
Fi ndCtrl ShapeByName, que nous allons maintenant expliquer. 

rem Codel3-01.ods bibli : Standard Modulel 
Option Explicit 

' retrouve la forme d'un controle de formulaire 
Function FindCtrl ShapeByName (unePage As Object, 

leFormulaire As String, leControle As String) As Object 
Dim objX As Object, x As Long 

for x = 0 to unePage . Count -1 
objX = unePage(x) 

i f objX . supportsService ("com . sun . star .drawn ng . Control Shape") then 
if objX. Control .Name = leControle then 

if objX. Control .Parent. Name = leFormulaire then 
Fi ndCtrl ShapeByName = objX ' forme trouvee 
Exit Function 
end if 
end if 
end if 
next 

End Function ' renvoi e Null en cas d'echec 

Cette fonction va analyser chacune des formes se trouvant dans la page, en effectuant 
des tests successifs : d'abord, elle verifie que la forme rend le service Control Shape (le 
nom du service de formes pour controles). Si c'est le cas, sa propriete Control nous 
donne le controle auquel elle est liee ; nous verifions que le nom de ce controle est 
bien celui recherche. Pour eviter les homonymies entre plusieurs formulaires, nous 
recuperons le formulaire dans lequel se trouve ce controle, grace a sa propriete 
Parent. Si le nom du formulaire est celui attendu, 1' objet forme est trouve et renvoye 
en resultat de la fonction. En cas d'echec, la fonction renverra la valeur Null, que 
l'appelant pourra tester avec la fonction IsNul 1 de OOoBasic. Si, dans la macro pre- 
cedente, vous modifiez dans l'appel de FindCtrl ShapeByName le nom du formulaire 
en FM2, vous trouverez l'autre controle de meme nom. 

La figure 13-2 represente en pointilles les chemins permettant de remonter vers le 
document formulaire, ils peuvent vous servir a l'occasion. 
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Les sous-formulaires 

Un objet sous-formulaire n'est pas accessible directement a partir de l'ensemble des 
objets formulaires de la page. En fait, il est vu comme un controle appartenant au 
formulaire parent, et on l'obtient de la meme facon qu'un autre controle : 

Dim lesFormulai res As Object 

Dim unFormul ai re As Object, sousFormul ai re As Object 
unFormul ai re = TesFormulai res.getByName("Sujets photos") 
sousFormulaire = unFormulaire.getByName("Cliches") 

Une fois en possession du sous-formulaire, vous avez acces de la meme facon aux con- 
troles qu'il contient, et eventuellement a un deuxieme niveau de sous-formulaire, etc. 



Fonctionnalites de base des contrdles 

Un formulaire n'est pas obligatoirement lie a une base de donnees. II peut servir a 
obtenir des renseignements qui seront ensuite imprimes, ou servir a declencher des 
macros du document. Inversement, tout controle de formulaire est rattache a un 
objet logiciel formulaire. Lorsque vous deposez un bouton sur une page d'un docu- 
ment Writer vierge, un objet formulaire est immediatement cree ; vous le constatez 
facilement avec le Navigateur de formulaires. 

Les controles sont pour la plupart similaires a ceux rencontres dans les boites de dia- 
logue. D'une maniere generale, le modele d'un controle de formulaire est equivalent 
au modele du controle analogue d'une boite de dialogue et la vue d'un controle de 
formulaire est similaire au controle lui-meme de la boite de dialogue. II existe cepen- 
dant de notables differences. 

Les proprietes de chaque controle sont nombreuses, tant au niveau du controle qu'au 
niveau de son modele. Vous trouverez dans le Zip telechargeable, dans le repertoire 
consacre a ce chapitre, le fichier PropsFormulai re.ods qui liste la plupart des pro- 
prietes de chacun des controles. 

Attacher une macro a un evenement d'un controle est identique a ce que nous avons 
vu avec les boites de dialogue. 

Le bouton 

Un bouton de formulaire sert en general a declencher une macro. Pour cela, on 
affecte le nom d'une macro existante a l'evenement Lors du declenchement, dans 
l'onglet Evenements du panneau des proprietes du controle. 
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Dans le panneau de proprieties d'un bouton, la propriete Action accepte differentes 
valeurs : 

• Aucun correspond a un bouton ordinaire. Pour realiser une action, on doit gerer un 
evenement de ce bouton, en lui affectant une macro. 

• Toute une serie de valeurs correspondant a des actions de navigation sur le formu- 
laire auquel le bouton est rattache. 

• L'action Ouvrir la page web permet effectivement de lancer l'affichage d'une page 
HTML sur le navigateur Internet par defaut. Mais elle peut aussi bien lancer tou- 
tes sortes d'URL, notamment celles des commandes de Dispatch ne necessitant 
pas d'argument. Par exemple, en mettant dans la propriete URL du panneau la 
valeur .uno:SearchDialog, appuyer sur le bouton affichera le dialogue de recher- 
cher-remplacer ; ou encore, la valeur . uno : CI oseWi n fermera la fenetre en cours. 

Le bouton picto ou bouton-image 

Ce controle est specifique aux formulaires. II sert a afficher une image, sans texte, et 
se declenche comme un bouton. On retrouve la propriete Action. 

Les zones de liste non liees a une base de donnees 

Dans une premiere approche, nous allons etudier les controles de type Zone de liste 
dont la liste des choix est definie en mode conception ou par programmation. 

Lorsque vous deposez une zone de liste sur un formulaire, l'Assistant entre en action 
pour configurer le lien vers la source de donnees. Annulez l'Assistant pour imposer 
une liste de choix non liee a une base de donnees. 

La zone de liste simple 

Son fonctionnement est identique a celui d'une boite de dialogue. L'objet Vue du 
controle (revoir la figure 13-2) expose les proprietes et methodes de gestion de la liste 
que nous avons listees au chapitre 11, section « Modifier le contenu d'une zone de 
liste ». Dans la macro suivante, nous affichons le rang et la valeur choisie dans une 
zone de liste a choix unique, puis nous selectionnons le choix de rang 1. 

rem Codel3-01.ods bibli : Mani pControl es Module2 
Option Explicit 

Sub ZoneDeListeO 

Dim monDocument As Object, maFeuille As Object 
Dim 1 esFormul ai res As Object, unFormulaire As Object 
Dim monCtrl As Object, vueCtrl As Object 
monDocument = thi sComponent 
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maFeuille = monDocument . Sheets. getByName("Formulai res") 

1 esFormul ai res = maFeui 11 e . DrawPage . Forms 

unFormulai re = lesFormulai res.getByName("FM2") 

monCtrl = unFormulai re. getByName("ChoixFruit") 

vueCtrl = monDocument. CurrentControl 1 er . getControl (monCtrl) 

print "Rang= " & vueCtrl .SelectedltemPos, vueCtrl .Selectedltem 

print "Selection du choix de rang 1" 

vueCtrl .selectItemPos(l, True) 

End Sub 

La propriete SelectedltemPos renvoie -1 si rien nest selectionne. 

Le principe de la zone de liste a choix multiple est similaire a ce que nous avons vu 
avec les boites de dialogue, une fois la vue du controle obtenue. 

rem Codel3-01.ods bibli : Mani pControl es Module3 
Option Explicit 

Sub ZoneDeListeChoixMultipleO 

Dim monDocument As Object, maFeuille As Object 

Dim 1 esFormul ai res As Object, unFormulai re As Object 

Dim monCtrl As Object, vueCtrl As Object 

Dim n As Long, listeSel As String 

monDocument = Thi sComponent 

maFeuille = monDocument. Sheets. getByName("Formulai res") 

1 esFormul ai res = maFeui 11 e . DrawPage . Forms 

unFormulai re = lesFormulai res .getByName("FM2") 

monCtrl = unFormulai re. getByName("Choix Couleurs") 

vueCtrl = monDocument . CurrentControl 1 er . getControl (monCtrl ) 

if UBound (vueCtrl . Sel ectedltemsPos) < 0 then 

MsgBox("Aucun element n'est selectionne") 
el se 

listeSel = "" 

for n = 0 to UBound (vueCtrl .Sel ectedltemsPos) 

listeSel = listeSel & vueCtrl . Sel ectedltemsPos(n) & " : " & 
vueCtrl .Selectedltems(n) & chr(13) 
nextobtenue . 

MsgBox(l i steSel , 0, "Elements sel ecti onnes") 
MsgBox("Suppression des elements sel ecti onnes") 
vueCtrl . sel ectltemsPos (vueCtrl . Sel ectedltemsPos , False) 
end if 

MsgBox("Selection des elements 2, 7, 8") 
vueCtrl .selectItemsPos(Array(7,2,8) , True) 
End Sub 
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La zone de liste combinee 

Son utilisation est similaire a celle vue dans une boite de dialogue, les proprietes et 
methodes listees dans la section « Modifier le contenu d'une zone de liste combinee » 
du chapitre 1 1 sont disponibles sur la vue du controle. 



La case a cocher 

Son utilisation est identique a celle vue dans une boite de dialogue. Ici aussi, la pro- 
priete State de l'objet controle peut prendre une des valeurs : 

0 La case n'est pas cochee. 

1 La case est cochee. 

2 Letat est « indetermine » ou « je ne sais pas » si le statut triple est active. 



Le choix 1 parmi N 

La maniere de creer un ensemble de cases de choix 1 parmi N (ou boutons radio) est 
tres differente de ce que nous avons vu avec les boites de dialogue. C'est la parfaite 
illustration qu'il y a plusieurs solutions a un meme probleme... 

La maniere la plus simple de creer un tel ensemble est de deposer une zone de 
groupe. Un Assistant vous guidera dans les etapes : 

1 Donner l'intitule de chaque bouton (le texte affiche). 

2 Selectionner un bouton par defaut. 

3 Donner une valeur a chaque option (la valeur referentielle, qui peut etre un texte). 

4 Donner l'intitule de la zone de groupe (le texte affiche en haut du cadre). 

Vous obtenez un ensemble de boutons regulierement espaces et entoures par un 
cadre. Cliquez n'importe ou dans le cadre : l'ensemble est selectionne, vous pouvez le 
deplacer en faisant glisser la souris. Cliquez ailleurs pour deselectionner. Maintenant, 
faites un Ctrl + die sur un des elements ; celui-ci seulement sera selectionne. Le Navi- 
gateur de formulaires facilite la selection d'un element. 

Dans un choix 1 parmi N de formulaire, tous les boutons recoivent le meme nom. 
C'est ainsi que le formulaire saura qu'ils fonctionnent ensemble. Done, si vous sou- 
haitez ajouter une autre option plus tard, deposez un controle Bouton radio et donnez 
lui ce meme nom. Comment distinguer le bouton choisi par i'utilisateur ? Nous 
avons besoin d'un element specifique. L'intitule du bouton pourrait convenir, mais il 
est susceptible d'etre modifie plus tard, soit pour le traduire dans une autre langue, 
soit pour des raisons de clarte. La valeur referentielle, definie a l'etape 3 convient 
mieux. Cependant, cette propriete RefValue du modele est normalement prevue 
pour etre envoyee a un serveur web apres validation du formulaire. Une autre solu- 
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tion totalement independante de l'usage du formulaire est d'utiliser la propriete Tag 
(Complement d'information) de chaque bouton. C'est ce que nous avons fait dans le 
document exemple. 

La recuperation du choix effectue par l'utilisateur est encore completement differente de 
ce que nous avons vu pour une boite de dialogue, comme le montre la macro suivante. 

rem Codel3-01.ods bibli : Mani pControl es Modulel 
Option Explicit 

Sub GroupelParmiNO 

Dim monDocument As Object, maFeuille As Object 
Dim lesFormulai res As Object, unFormulaire As Object 
Dim opinionO As Object, alternative As Object 
monDocument = thi sComponent 

maFeuille = monDocument . Sheets . getByName("Formul ai res") 
1 esFormul ai res = maFeui 11 e . DrawPage . Forms 
unFormulaire = lesFormulai res .getByName("FMl") 
unFormulaire. getGroupByName("avisDuCl ient" , opinionO) 
for each alternative in opinionO 
With alternative 

MsgBox("Label= " & .Label & chr(13) & _ 

"Tag= " & .Tag & chr(13) & "Etat= " & .State) 

End With 
next 
End Sub 

Apres avoir recupere l'objet formulaire, nous utilisons sa methode getGroupByName. 
Le premier argument est le nom commun a tous les boutons du groupe (attention, ne 
pas confondre avec le nom du controle zone de groupe). La methode affectera au 
deuxieme argument un tableau d'objets, chacun d'eux etant un des boutons. Signa- 
lons qu'il n'y a aucune raison de supposer que les elements du tableau sont dans 
l'ordre des boutons, car les boutons ont pu etre deplaces en mode conception. Le 
tableau obtenu est explore par une boucle For Each ; pour la demonstration, nous 
affichons 1'intitule du bouton. La valeur de la propriete Tag servant a distinguer 
chaque alternative de choix, prenez des valeurs qui simplifient votre programme. La 
propriete State vaut 1 si le bouton est choisi, 0 s'il ne Test pas. 

Naturellement, il est aussi possible d'utiliser un evenement comme Lors du declenche- 
ment sur chacun des boutons. 

Les champs de saisie 

II s'agit des controles Zone de texte, Champ numerique, Champ date, Champ 
horaire, Champ monetaire, Champ masque, Champ formate. 
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Leur utilisation est identique a celle vue dans une boite de dialogue. La valeur cou- 
rante est obtenue directement depuis une propriete du modele (voir le tableau 13-1). 

Tableau 13-1 Proprietes donnant la valeur actuelle d'un controle 
Significa 



Texte Text String Texte affiche. 


Numerique 


Value 


Double 


Valeur. 


Monetaire 


Value 


Double 


Valeur. 


Masque 


Text 


String 


Texte affiche. 


Formate 


Text 


String 


Texte affiche. 


Date 


Date 


Long 


Date au format ISO, voir le chapitre 11, section « Le champ de 
date » 


Heure 


Ti me 


Long 


Heure au format d'un entier, voir le chapitre 1 1 , section « Le 
champ horaire ». 



Pour un controle Numerique ou Monetaire, le texte affiche est obtenu par la pro- 
priete Text de la vue du controle. 



Ctrl. Value renvoie : 123456.57 
vueCtrl .Text renvoie : € 123 456,57 



Pour les controles Date et Heure, le texte affiche est obtenu par la propriete Text de 
l'objet Peer de la vue du controle. 



Ctrl. Date renvoie : 19540714 

vueCtrl .Peer. Text renvoie : 1954-07-14 



La zone de texte avec formatage 

Dans le panneau de proprietes du controle Zone de texte, si la propriete Type de texte 
est configuree a Plusieurs lignes avec formatage, on obtient une zone ayant les memes 
possibilites de formatage qu'une zone de texte dans Writer, et sans limitation du 
nombre de caracteres. 

rem Codel3-07 . odt bibli : Standard Modulel 
Option Explicit 

Sub Ecri reTexteFormateO 

Dim monDocument As Object, leFormulaire As Object, zTexte As Object 
Dim monTexte As Object, monCurseur As Object 
Dim finLigne As Integer 
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finLigne = com . sun . star . text . Control Character . PARAGRAPH_BREAK 

monDocument = Thi sComponent 

1 eFormul ai re = monDocument . Drawpage . Forms(O) 

ztexte = 1 eFormul ai re. getByName("TextBox") 

monTexte = zTexte 

monCurseur = monTexte. createTextCursor 
With monCurseur 

.gotoStart(False) 

.gotoEnd(True) 

.String = "" ' raz du texte existant 
.CharPosture = com . sun . star . awt . FontSl ant . NONE 
.CharWeight = com. sun . star . awt . FontWei ght . BOLD 
.CharColor = RGB(255, 50, 50) 
.CharHeight = 12 

monTexte. insertString(monCurseur, "Bonjour tout le monde,", False) 
monTexte. i nsertControl Character(monCurseur , finLigne, False) 
.CharWeight = com. sun . star . awt . FontWei ght . NORMAL 
.CharColor = -1 
.CharHeight = 10 

.CharPosture = com . sun . star . awt . FontSl ant . ITALIC 

monTexte. insertString(monCurseur, "Comment allez-vous ?", false) 

monTexte. i nsertControl Character(monCurseur, finLigne, False) 

End With 

End Sub 

Le texte au sens Writer est obtenu par le controle lui-meme. Ici, on a simplement 
change le nom de la variable pour retrouver le style de codage employe au chapitre 8. 

Le compteur 

II s'agit en fait de deux boutons fieche groupes a l'horizontale ou a la verticale. L'un 
incremente, l'autre decremente un compteur de valeur entiere Long. L'orientation, les 
valeurs limites et l'increment sont reglables dans le panneau de proprietes. La valeur 
courante du compteur n'est pas affichee sur le formulaire, on l'obtient par la propriete 
Spi nVal ue du modele du controle. 



Le controle Image ou controle Picto 

Ce controle est ameliore avec la version 3.1 d'OpenOffice.org sur les points 
suivants : 

• Dans le panneau des propriete, Echelle permet de conserver les proportions de 
l'image a l'affichage. 

• Lorsqu'on affecte au controle une image via le panneau des proprietes, le dialogue 
permet de decocher la case Lien, afin d'integrer l'image dans le document lui-meme. 
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• Lorsque le controle est lie a un champ de la table, ce champ est interprete comme 
contenant l'adresse URL de l'image. Ainsi, la base de donnees d'images ne con- 
tient que les adresses, et les fichiers images sont externes a la base. 

Autres contrdles 

II s'agit des controles : 

• Selection de fichier ; 

• Barre de defilement. 

Leur utilisation est identique a celle vue dans une boite de dialogue. 

II nous reste a voir les controles specifiques aux bases de donnees, ainsi que la gestion 
des controles quand ils sont lies a une base de donnees. 

Principes communs aux contrdles 
Imposer le focus sur un controle 

Nous avons defini la notion de focus au chapitre 11 « Les boites de dialogue », et 
montre comment mettre le focus sur un controle de dialogue. La methode est simi- 
laire pour un controle de formulaire. On utilise la methode setFocus de la vue du 
controle concerne. 

unCtrl = unFormulai re . getByName("DateNai ss") 

vueCtrl = monDocument.CurrentController.getContro"! (unCtrl) 

vueCtrl . setFocus 

Remettre le focus sur le document 

Quand on effectue une action sur un controle de formulaire, le focus passe sur le for- 
mulaire. Par exemple, avec Writer, si on clique un bouton le curseur courant n'appa- 
rait plus sur le document, ce qui est genant pour l'utilisateur. Avec Calc, on le voit si 
une cellule est en mode edition. 

En fin d'execution de la macro appelee par le controle, ces instructions remettent le 
focus sur le document : 

Dim w As Object 

w = Thi sComponent . CurrentControl 1 er . Frame . Contai nerWi ndow 
w. setFocus 
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Rendre un contrdle invisible 

La methode setVisible de la vue du controle le rend invisible avec l'argument 
Fal se. La methode i sVi si bl e renvoie True si le controle est visible. 

vueCtrl .Visible = False 

if vueCtrl . isVisible then .... 

Gerer les evenements d'un contrdle 

On affecte une macro a un des evenements du controle (onglet Evenements du pan- 
neau de proprietes). Comme pour un dialogue, la macro gerant l'evenement recoit un 
objet evenement en argument. Cet objet expose une propriete Source qui permet, 
grace a sa propriete Parent, de remonter jusqu'a l'objet formulaire auquel est rattache 
le controle. 

Sub traitement(evt As Object) 

Dim vueCtrl As Object, Ctrl As Object, formulaire As Object 

vueCtrl = evt. Source 
Ctrl = vueCtrl . Model 
formulaire = Ctrl. Parent 
End Sub 

On retrouve avec les controles de formulaire les evenements que nous avons decrits 
pour les controles de dialogue dans le chapitre 11, a la section « Les principaux 
evenements ». Lorsque le controle est lie a un champ de base de donnees, d'autres 
evenements peuvent se produire, comme nous le verrons plus loin dans ce chapitre a 
la section « Les evenements des formulaires ». 

Gestionnaire d'evenements commun a plusieurs controles 

De meme que pour les dialogues, il est tout a fait possible d'affecter le meme gestion- 
naire d'evenements a plusieurs controles. Void un exemple simple, que vous pouvez 
tester en mettant plusieurs boutons sur un document Writer, et en affectant un 
meme gestionnaire a l'evenement lors du declenchement. Pour chaque bouton, avec 
le panneau Proprietes de l'EDI, remplissez la propriete Complement d'information avec 
un texte quelconque, specifique a chacun. 

Sub Gestionnai reMultiple(Evenement As Object) 
Msgbox (Evenement .Source. Model .Tag) 
End Sub 
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Notre gestionnaire recupere la vue du controle declencheur avec la propriete Source de 
l'objet evenement. Le modele du controle est obtenu par la propriete Model de la vue, 
et la propriete Tag correspond a Complement conformation dans l'EDI. Vbus pouvez 
aussi bien acceder aux autres proprietes, comme le nom du controle par exemple. 

Formulaire intelligent 

Vous trouverez dans l'API (voir l'annexe A) un exemple tres instructif et realiste d'un 
formulaire pour passer une commande a un fast-food: burger_factory .odt. A 
chaque valeur introduite dans un controle, des Listener mettent a jour d'autres con- 
troles du formulaire. Vbus trouverez le formulaire dans le sous-repertoire du SDK : 

/exampl es/basi c/f orms_and_control s/ 



Les contrdles de formulaire dans Calc 

La plupart des controles de formulaire peuvent etre lies a une cellule du document Calc 
dans lequel ils sont deposes. Par exemple, deposez une zone de texte sur une feuille 
d'un document Calc. Dans le panneau Proprietes, a l'onglet Donnees, remplissez le 
champ Cellule Nee avec la valeur D4. Une fois le mode conception desactive, tapez un 
texte dans la zone de texte : il apparait dans la cellule D4 de la feuille. Editez le contenu 
de la cellule D4 : le nouveau contenu apparait dans la zone de texte. La cellule liee a 
son propre format d'affichage, sans lien avec l'affichage du controle. 

Les controles autorisant un lien avec Calc sont : Zone de texte, Champ numerique, 
Champ formate, Case a cocher, Bouton Radio, Zone de liste simple, Zone de liste 
combinee, Compteur, Barre de defilement. 

A quoi cela peut-il bien servir ? Le document Codel3-06.ods du Zip telechargeable 
comporte un formulaire a remplir sur la feuille Remplir, et une exploitation du con- 
tenu des controles sur la feuille Resultats. Dans cet exemple, le controle utilise pour 
la valeur d'heure n'accepte qu'une valeur comprise entre 0 et 23, et permet une incre- 
mentation/decrementation par boutons. 

De plus, un controle Zone de liste simple ou Zone de liste combinee peut utiliser une 
liste de valeurs situee dans une zone de cellules du document Calc. Dans le docu- 
ment exemple, le choix d'une couleur est une zone de liste simple, le choix d'une des- 
tination est une zone de liste combinee, et ces listes sont dans la feuille Fliste. Ici 
aussi, la zone de cellules et la liste du controle sont liees : si on change la valeur d'une 
des cellules de la zone servant a la liste, la liste du controle se met a jour. Si on insere 
des lignes dans la zone de cellules, la liste insere les nouveaux elements. 
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Pour un controle Zone de liste, la cellule liee peut contenir soit le texte de l'element 
choisi, soit le rang de cet element dans la liste. Le rang est plus pratique pour 
l'exploitation informatique. Pour une zone de liste combinee, la cellule reproduit le 
texte choisi ou tape par l'utilisateur. 

Par programmation, il est possible de changer l'adresse de la cellule liee, et la zone de 
cellules servant a la liste. Dans le document exemple, actionner le bouton Changer la 
liste declenche la macro suivante qui modifie le controle Zone de liste combinee : 

rem Codel3-06.ods bibli : Standard Modulel 
Option Explicit 

Sub changerZonesLieesO 

Dim monDocument As Object, leFormulaire As Object, lien As Object 
Dim maCellule As Object, maZone As Object, monCombo As Object 
Dim fRemplir As Object, fResultats As Object, fListe As Object 
Dim prop(O) As New com. sun. star. beans. NamedValue 

monDocument = Thi sComponent 

fResultats = monDocument . Sheets . getByName("Resul tats") 
fListe = monDocument. Sheets. getByName("Fliste") 
fRemplir = monDocument . Sheets . getByName("Rempl i r") 
leFormulaire = fRempl i r . Drawpage . Forms . getByName("Standard") 
monCombo = leFormulai re.getByName("Choix destinations") 

Select Case InputBox("Numero de configuration : 1 ou 2", "", "1") 
case "2" 

maCellule = fRempl i r . getCel 1 RangeByName("D7") 
maZone = f Li ste . getCell RangeByName("F22 : F30") 
Case Else 

maCellule = f Resul tats . getCell RangeByName("B5") 
maZone = fListe. getCellRangeByName("F4: F16") 
End Select 

' changer le lien vers la cellule resultat 
prop (0) .Name = "BoundCell" 
prop(O) . Val ue = maCellule. Cell Address 
lien = monDocument. createlnstanceWithArgumentsC 
"com . sun . star . tabl e . Cel 1 Val ueBi ndi ng" , propO) 
monCombo . setVal ueBi ndi ng (lien) 

' changer le lien vers la zone de cellules contenant la liste 

prop (0). Name = "Cell Range" 

prop(O) . Val ue = maZone. RangeAddress 

lien = monDocument. createInstanceWithArguments(_ 

"com . sun . star . tabl e . Cel 1 RangeLi stSource" , propO) 
monCombo. setListEntrySource(l ien) 

1 reinitialiser le Texte du combo, qui n'a pas ete modifie 
monCombo. Text = "" 
End Sub 
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Les methodes setValueBinding et setLi stEntrySource du controle recoivent un 
objet decrivant le lien. Pour cela, on invoque deux services specialises en leur trans- 
mettant une structure, qui n'est pas une PropertyVal ue mais une NamedVal ue, tres 
similaire. Cette structure recoit les coordonnees de la cellule ou de la zone. 

Memoriser une information cachee dans un controle 

La propriete Tag (Complement d'information) d'un controle est rarement utilisee, sur- 
tout dans un controle Etiquette. Cette propriete contient une chaine de caracteres 
quelconque, pouvant atteindre 65 535 caracteres. Dans un document formulaire, on 
peut done l'employer sur un ou plusieurs controles pour memoriser des informations 
de programmation que l'utilisateur n'a ni a connaitre, ni a modifier. 

Dans un document sans formulaire apparent, on peut toujours ajouter un ou plu- 
sieurs controles Etiquette de taille reduite et avec un titre vide, ils seront invisibles 
mais pourront contenir une information dans Tag. On pourra les retrouver et les 
selectionner avec le Navigateur de formulaire. 



Controles et base de donnees 

La plupart des controles peuvent etre lies a une base de donnees, ce qui permet a 
l'utilisateur de visualiser le contenu de certains elements et de les modifier facile- 
ment. II est important de se rappeler les points suivants : 

• Un objet formulaire est lie au maximum a une source de donnees (une base de 
donnees). 

• Dans cette base de donnees, un objet formulaire ne peut gerer qu'une seule table, 
ou resultat d'une instruction SQL, ou requete enregistree. Le resultat d'une ins- 
truction SQL est l'equivalent d'une table creee dynamiquement ; une requete est 
en fait une instruction SQL. 

• Les controles orientes donnees affichent un champ dans cette table (sauf le con- 
trole Table, que nous allons voir, qui en affiche un par colonne). 

• Les objets sous-formulaires permettent de gerer d'autres tables de la meme base 
de donnees que le formulaire principal auquel ils sont rattaches. Ils recherchent 
les enregistrements d'une autre table dont un champ a la meme valeur qu'un 
champ de la table principale. Notez egalement qu'un sous-formulaire peut lui- 
meme comporter un ou plusieurs sous-formulaires. 
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L'objet formulaire 

Le formulaire permet d'acceder a une table et d'y naviguer. II possede les proprietes 
et methodes que nous avons vues au chapitre 12 pour un RowSet, et ajoute les siennes 
propres : 

• La methode isLoaded de l'objet formulaire renvoie True lorsqu'il est complete- 
merit charge. Si vous ouvrez par programme un document formulaire, attendez la 
fin du chargement de l'objet formulaire avant de l'utiliser. 

• La methode reload de l'objet formulaire permet de rafraichir les donnees en re- 
executant la commande du RowSet. 

• La methode createResultSet cree un ResultSet utilisant la meme commande 
SQL que le Rowset du formulaire. Nous verrons un exemple d'utilisation avec le 
controle Table. 

La barre de navigation 

Ce controle est en fait une barre d'outils qu'on pose sur le document. II permet de 
changer d'enregistrement courant dans la table du formulaire, et offre divers boutons. 
Vous pouvez choisir d'afficher ou masquer certains d'entre eux. 

Le controle Table 

Le controle de table, ou plutot grille (grid, en anglais) sert a visualiser les champs 
d'une table, a changer leur contenu, a inserer ou a supprimer des enregistrements. II 
est done tres courant dans un document formulaire utilisant une base de donnees, 
mais n'est pas indispensable. Bien qu'il ressemble a une feuille de tableur, un controle 
Table n'a pas les fonctionnalites d'un tableur. 

Chaque colonne d'un controle Table est lui-meme un des controles que nous avons 
deja vus. L'objet Table expose ses colonnes sous forme d'une collection dont chaque 
element est accessible par indexation ou par le nom (propriete Name) de la colonne. 
Ne confondez pas cette propriete avec l'en-tete de la colonne que voit l'utilisateur 
(propriete Label). 



Bon a savoir 

Les affectations de macro aux evenements de controles de colonne dans un controle Table sont actuelle- 
ment ignorees. Seuls les controles deposes sur la page du document peuvent declencher des macros sur 
un evenement. 
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Dans l'exemple suivant, nous avons cree un formulaire sur la table CI i ents de la base 
de donnees BDDext du chapitre 12. Nous aurions pu faire l'equivalent avec la base 
BDDi nt. Dans ce formulaire, un controle Table a ete depose en utilisant 1' Assistant, 
pour afficher les colonnes NOM, PRENOM, NAISS. Nous avons renomme ensuite les 
valeurs par defaut des noms des objets colonnes et des en-tetes de colonnes. Nous 
avons ajoute sur la page quelques autres controles pour visualiser le nom du client (en 
lecture seule) et son adresse. Avec un clic droit sur chaque controle, nous avons 
change l'ancrage en A la page pour faciliter le positionnement. Enfin, en affichant les 
proprietes du formulaire, nous avons effectue un tri dans l'ordre decroissant des dates 
de naissance. Ceci vous donne un apercu des facilites de formulaire. 

rem Codel3-01 . odt bibli : ModifTable Modulel 
Option Explicit 

Sub Expl orerFormul ai re() 

Dim monDocument As Object, unFormulaire As Object, grille As Object 
Dim ctrColNaiss As Object, ctrlAdresse As Object, colTable As Object 
Dim uneColonne As Object, x As Long 
monDocument = Thi sComponent 

unFormul ai re = monDocument . DrawPage . Forms . getByName("MajCl i ent") 
grille = unFormul ai re . getByName("Tabl eControl ") 
for x = 0 to grille. Count -1 
uneColonne = grille(x) 

MsgBox ("Nom du controle = " & uneCol onne . Name & chr(13) & _ 
"En-tete de colonne = " & uneCol onne . Label & chr(13) & _ 
"Type du controle = " & chr(13) & uneCol onne. Col umnServiceName , 0, _ 
"Controle Table, colonne " & x) 

next 

' trois manieres d'acceder a 1 ' enregi strement courant 

ctrColNaiss = grille. getByName("Annee Naissance") 

ctrlAdresse = unFormulaire. getByName("Rue") 

colTable = unFormulaire. Columns. getByName(" PRENOM") 

MsgBox("Prenom : " & colTable. String & chr(13) & _ 

"Annee de naissance : " & ctrCol Nai ss . Val ue & chr(13) & _ 
"Adresse : " & ctrlAdresse. Text, 0, "Client en cours") 

End Sub 

Nous commencons par recuperer dans le document le formulaire nomme MajCl i ent, 
puis le controle Table nomme Tabl eControl. Sa propriete Count nous donne le 
nombre de colonnes que le controle affiche, et on accede a chaque objet colonne avec 
la methode getBylndex. Avec OOoBasic, le getBylndex peut etre omis, comme si on 
indexait une variable tableau. La boucle For affiche successivement pour chaque 
colonne le nom de du controle, le libelle de l'en-tete de colonne, et le type du con- 
trole ce qui nous permet de voir que les deux premieres colonnes sont des champs 
Texte, et la troisieme un champ numerique. 
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Nous allons maintenant recuperer des valeurs correspondant a l'enregistrement cou- 
rant (celui pointe par la fleche du controle Table). Pour la demonstration plusieurs 
methodes sont utilisees. 

• L'annee de naissance est obtenue a partir du controle de la colonne « Ne en » du 
controle Table. La valeur numerique est recuperee par sa propriete Val ue. 

• L'adresse est obtenue a partir du controle Zone de Texte « Rue ». Sa propriete 
Stri ng nous donne la valeur de ce champ. 

• Le prenom n'est disponible dans aucun des controles de l'objet formulaire. Mais 
ce dernier interroge la table Clients, et possede les fonctionnalites d'un RowSet 
qui lui-meme herite des fonctionnalites d'un ResultSet. On peut done recuperer 
la valeur courante du prenom dans la colonne PRENOM de la table CI i ents. Ici nous 
avons choisi une des trois manieres d'y arriver, relisez au besoin la section 
« Explorer les resultats d'une requete » du chapitre 12. Bien entendu, si le formu- 
laire avait ete base sur le resultat d'une requete plus specialisee, il aurait fallu utili- 
ser les noms de colonnes fournis par la requete. 

Ainsi, il n'est pas necessaire de mettre toutes les colonnes disponibles dans un con- 
trole Table. II est meme possible de s'en passer et n'utiliser que les autres controles, 
pour les seules colonnes necessaires a l'utilisateur. 

Connaitre la selection dans le controle Table 

L'utilisateur dispose de plusieurs moyens de selection : 

• placer le curseur dans une des cellules affichees par le controle Table ; 

• ou bien selectionner une ligne en cliquant sur la marge gauche du controle ; 

• ou encore selectionner plusieurs lignes avec Maj + die et/ou Ctrl + die sur la marge ; 

• enfin, selectionner le contenu entier en cliquant sur la marge en haut a gauche. 
Le codage ci-dessous traite ces differents cas. 

rem Codel3-02 . odt bibli : ModifTable Module2 
Option Explicit 

Sub SelectionDansControleTableO 

Dim monDocument As Object, unFormul ai re As Object 

Dim grille As Object, vueGrille As Object 

Dim lignesSel As Variant, rs As Object, positionLigne As Variant 
monDocument = thi sComponent 

unFormul ai re = monDocument . DrawPage . Forms . getByName("MajCl i ent") 

grille = unFormul ai re . getByName("Tabl eControl ") 

vueGrille = monDocument. CurrentController.getControl (grille) 

lignesSel = vueGrille. Selection 

if UBound(lignesSel) < 0 then 

MsgBox("Position courante :" & chr(13) & _ 



Les formulaires 

Chapitre 13 



gr-me(l) .Text & " " & grille(O) .Text & chr(13) & _ 

"Le curseur est en colonne " & vueGrille.CurrentColumnPosition & 

" du controle Table", 0, "Pas de ligne selectionnee") 

el se 

rs = unFormulaire.createResultSet 

for each positionLigne in lignesSel() 
"if rs.moveToBookmark(positionLigne) then 

' acces par rang de colonne du ResultSet, a parti r de 1 
MsgBox(rs.getString(3) & " " & rs .getString(2) , 0, 
"Ligne selectionnee") 

el se 

MsgBox("Signet non trouve ! ", 16) 
end if 
next 
end if 
End Sub 

L'analyse se fait a partir de la vue du controle, obtenue a partir de la propriete 
CurrentController du document. Dans cetobjet vueCri lie, la propriete Selection est 
un tableau representant les lignes selectionnees. Si le tableau est vide (son index maximal 
est negatif ), il y a au plus une cellule selectionnee, ou le curseur est dans une cellule. 

Dans ce premier cas le modele du controle Table nous fournit les valeurs de chaque 
champ de la ligne, et nous recuperons le prenom et le nom en utilisant la pseudo- 
indexation de Basic sur la collection des colonnes de la grille (encore une autre methode 
d'acces). La propriete CurrentColumnPosition de la vue du controle nous renseigne sur 
la position de la cellule courante, relativement aux colonnes du controle Table. 

Dans le cas ou le tableau renvoye par la propriete Selection nest pas vide, il contient 
un signet (bookmark) par ligne selectionnee. L'utilisation des signets a ete expliquee au 
chapitre 12, section « Exploiter les resultats d'une requete ». Nous avons auparavant 
« clone » un ResultSet a partir du RowSet de l'objet formulaire (methode 
createResultSet). Ce ResultSet nous sert a balayer toutes les lignes du resultat sans 
perturber i'etat du RowSet. La methode moveToBookmark nous positionne sur la ligne 
de la table correspondant a une des lignes selectionnees sur la grille. Pour varier les plai- 
sirs, nous affichons le prenom et le nom de la ligne en utilisant les index de colonne 
relatifs au Resul tSet, done sans rapport avec la disposition des colonnes dans la grille. 

Deplacer la position courante dans le controle Table 

En fait, deplacer la ligne courante du controle Table est tres simple. II suffit d'utiliser 
les methodes de navigation du ResultSet du formulaire, comme nous l'avons fait au 
chapitre 12. Le controle Table n'est qu'un afficheur, esclave du ResultSet. 

I rem Codel3-02 . odt bibli : Modifiable Module3 
Option Explicit 
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I Sub SeDeplacerDansLeControleTableO 
Dim monDocument As Object, unFormul ai re As Object 

monDocument = thi sComponent 

unFormul ai re = monDocument . DrawPage . Forms . getByName("MaJCl i ent") 
MsgBox("Position actuelle : " & unFormul aire. Row & chr(13) & _ 

"Cliquez OK pour aller a la ligne 2") 
unFormul ai re . absol ute (2) 

MsgBox("Position actuelle : " & unFormul ai re . Row & chr(13) & _ 

"Cliquez OK pour aller a la derniere ligne") 
unFormulai re. last 

MsgBox("Position actuelle : " & unFormul ai re . Row & chr(13) & _ 

"Cliquez OK pour remonter de 4 lignes") 
unFormulai re. rel ative(-4) 

MsgBox("Position actuelle : " & unFormul ai re . Row & chr(13) & _ 

"Cliquez OK pour aller a la ligne suivante") 
unFormul ai re . next 

MsgBox("Position actuelle: " & unFormul ai re . Row) 
End Sub 



Modifier le contenu d'un champ du formulaire 

Dans l'utilisation d'un formulaire, le passage a un autre enregistrement est une valida- 
tion implicite des modifications de la ligne en cours effectuees par l'utilisateur. La base 
de donnees utilisee par le formulaire est alors automatiquement mise a jour. II existe 
aussi un bouton sur la barre de navigation de formulaire pour valider la ligne. A l'inverse, 
l'utilisateur a plusieurs moyens pour annuler les modifications avant validation : il peut 
soit appuyer sur la touche Echap quand il est sur un champ du controle Table, ou alors 
actionner un autre bouton sur la barre de navigation de formulaire. 

Si on change par programme la valeur d'un champ de formulaire, ceci n'est pas reper- 
cute immediatement sur la ligne en cours. Pour chaque controle dont on a modifie la 
valeur, il faut executer la methode commi t. Cet exemple le demontre. 

rem Codel3-02 . odt bibli : ModifTable Module4 
Option Explicit 

Sub ModifierValeurO 

Dim monDocument As Object, unFormulai re As Object, grille As Object 
Dim ctrColNaiss As Object, ctrlAdresse As Object 
monDocument = Thi sComponent 

unFormul ai re = monDocument .DrawPage . Forms . getByName("MajCl i ent") 
grille = unFormul ai re . getByName("Tabl eControl ") 
ctrColNaiss = grille. getByName("Annee Naissance") 
ctrlAdresse = unFormulai re. getByName("Rue") 
ctrColNaiss. Value = 2005 
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Ctrl Adresse. Text = "18, avenue des Hi rondel! es" 

if MsgBox("Prendre en compte les nouvelles valeurs ?", 4) = 6 then 

Ctrl Adresse .commit 

ct rCol Nai ss . comnri t 
end if 
End Sub 

La macro va modifier la date de naissance et l'adresse du client en cours. Lancez-la 
d'abord en repondant Non a la question. Le champ Ne en ne change pas (probable- 
ment un effet de l'integration du controle numerique dans le controle Table), mais le 
champ Adresse change. Passez a l'enregistrement suivant et revenez sur l'enregistre- 
ment initial : les valeurs sont bien revenues aux valeurs initiales, preuve que la base de 
donnees n'a pas ete mise a jour. 

Relancez la macro en repondant Oui a la question. Les deux champs changent de 
valeur, l'indicateur d'enregistrement modifie apparait en marge du controle Table. 
En tapant sur la touche Echap, les changements sont annules. Relancez encore en 
repondant Oui, passez a l'enregistrement suivant et revenez sur l'enregistrement 
initial : les valeurs sont bien modifiees. 

Zone de liste et base de donnees 

Les controles Zone de liste peuvent offrir un choix obtenu a partir d'une table. 
LAutopilote facilite la configuration du controle pour cet usage. Dans une telle con- 
figuration, le controle Zone de liste oblige a selectionner un element et un seul. Ceci 
est normal, car le choix resultant sera stocke dans un champ de table. 

Le document exemple Codel3-05 .odt presente plusieurs formulaires utilisant la base 
de donnees BDDext. Rappelons que ces exemples n'ont qu'un but didactique, une 
vraie gestion commerciale est bien plus complexe. 

Lencadre Gestion des factures est un formulaire servant a modifier ou ajouter un enre- 
gistrement dans la table Factures. II utilise une zone de liste pour choisir le nom du 
client depuis une requete sur la table Clients, et le choix obtenu servira a remplir le 
champ CLIENT de la table Factures avec le numero (et pas le nom) du client. Ce 
numero est le champ REF de la table Clients. Les controles affichant le prenom et 
l'adresse du client sont obtenus par un sous-formulaire. 

Cliquez sur la liste deroulante du nom de client, et remontez en haut de la liste : vous 
observez une ligne vide. Cette ligne est ajoutee automatiquement a la liste affichee, 
elle correspond a la valeur Null pour le champ. Dans des bases de donnees plus ela- 
borees (telle la base interne HSQLDB), on peut specifier si une valeur Null est 
acceptable pour un champ. 
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La requete employee pour la liste deroulante donne une liste en ordre alphabetique 
des noms. Vous remarquerez qu'il y a deux « Durand ». Le probleme des homonymes 
ne se resout qu'avec un numero de client. Mais, lorsque Ton cree une facture, on part 
d'un client : il nous faut visualiser tous les elements permettant de s'assurer de son 
identite. Cependant, si on selectionne un autre nom que l'actuel, les champs prenom, 
rue, code postal, ne changent pas ! En effet, ces champs ne refletent que le contenu 
actuel de l'enregistrement dans la table Factures. II hy a pas de moyen d'afficher 
simplement les valeurs correspondant a un choix non valide. Cette maniere de pro- 
ceder ne convient done pas. Une autre solution serait de choisir d'abord un client, 
puis de transferer son numero dans l'enregistrement de Factures. 

Lencadre Vente d'articles est un formulaire permettant de modifier ou d'ajouter un 
enregistrement dans la table Ventes. Chaque type d'objet vendu fait l'objet d'un 
enregistrement, avec une reference a un numero de facture. Ici, la liste de choix se 
justifie, car chaque libelle d'article est suppose different. 

Nous n'avons pas eu besoin de programmer, mais seulement de definir les formu- 
laires et leurs controles. Etudiez leur configuration avec le Navigateur de formulaires 
et le panneau des proprietes de controles. Les formulaires Gestion des factures et 
Vente d'articles fonctionnent, faites des manipulations et affichez ensuite le con- 
tenu des tables. D'autres formulaires seraient utiles, par exemple pour lister les arti- 
cles d'une facture, ou les factures d'un client. 

Les evenements des formulaires 

Longlet Evenements du panneau de proprietes de l'objet formulaire ainsi que chacun 
de ses controles lies a un champ de donnees presentent la plupart des evenements 
utiles, ce qui peut eviter de mettre en place un Listener (le principe d'un gestionnaire 
d'evenements, ou Listener, est expose au chapitre 14). 

Le tableau 13-2 liste, pour un objet formulaire, les noms d'evenements en francais, le 
terme anglais equivalent, la correspondance probable avec l'interface et la routine de 
Listener concernees. II indique egalement si le gestionnaire a un droit de 
veto (colonne V) sur l'evenement. Pour de tels evenements, la routine de gestion est 
une fonction qui renvoie True si l'evenement est autorise, Fal se s'il doit etre interdit. 
S'il y a plusieurs gestionnaires sur le meme evenement, la priorite est donnee a Fal se. 
Pour ce panneau comme pour le suivant, la traduction francaise peut varier, mais le 
tableau liste les evenements dans l'ordre d'affichage sur le panneau. 
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Tableau 13-2 Evenements sur un objet formulaire 
Interface 



Avant de retablir 


Prior to reset 


XResetLi stener 


approveReset 


V 


Apres le retablissement 


After resetting 


XResetLi stener 


resetted 




Avant I'envoi 


Before submitting 


XSubmitLi stener 


approveSubmit 


V 


Lors du chargement 


When loading 


XLoadLi stener 


loaded 




Avant le rechargement 


Before reloading 


XLoadLi stener 


reloading 




Lors du rechargement 


When reloading 


XLoadLi stener 


rel oaded 




Avant le dechargement 


Before unloading 


XLoadLi stener 


unl oadi ng 




Lors du dechargement 


When unloading 


XLoadLi stener 


unl oaded 




Confirmation de suppression 


Confirm deletion 


XConfi rmDeleteLi stener 


confi rmDelete 


V 


Avant I'operation 
d'enregistrement 


Before record action 


XRowSetApproveLi stener 


approveRowchange 
approveRowSetchange 


V 
V 


Apres I'operation 
d'enregistrement 


After record action 


XRowSetLi stener 


rowChanged 
rowSetChanged 




Avant le changement 
d'enregistrement 


Before record change 


XRowSetApproveLi stener 


ApproveCursorMove 


V 


Apres le changement 
d'enregistrement 


After record change 


XRowSetLi stener 


cursorMoved 




Remplir les parametres 


Fill parameters 


XDatabaseParameterLi stener 


approveParameter 


V 


Erreur survenue 


Error occurred 


XSQLErrorLi stener 


errorOccured (cf. Note) 





Note 

Le nom de la routine errorOccured comporte une faute d'orthographe, qui sera perpetuee pour des 
raisons de compatibility. 



Le tableau 13-3 liste les evenements concernant la base de donnees qui apparaissent 
en fin de liste sur l'onglet Evenements du panneau de proprietes des controles orientes 
donnees. L'evenement Erreur survenue n'existe que pour un controle Table. 

Tableau 13-3 Evenements sur un controle 



Avant de retablir 


Prior to reset 


XResetLi stener 


approveReset 


V 


Apres le retablissement 


After resetting 


XResetLi stener 


resetted 




Avant I'actualisation 


Before updating 


XUpdateLi stener 


ApproveUpdate 


V 


Apres I'actualisation 


After updating 


XUpdateLi stener 


updated 




Erreur survenue 


Error occurred 


XSQLErrorLi stener 


errorOccured 
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Le document Codel3-O3.odt demontre 1'utilisation d'evenements sur le formulaire. 
II utilise trois macros lancees sur evenement. Le formulaire utilise la base BDDext, 
table Clients. Les boutons Supprimer I'enregistrement en cours, Enregistrer la saisie, 
Annuler la saisie ont leur propriete Action positionnee sur 1' action correspondante, qui 
est alors executee automatiquement. 

Le bouton Afficher les evenements modifie le comportement des macros attachees aux 
evenements. Commencez par manipuler le formulaire sans actionner ce bouton. 
Voyez le comportement des trois autres boutons, qui passent a l'etat grise s'il n'y a pas 
de modification en cours. Voyez Taction du bouton Annuler la saisie : toutes les modi- 
fications en cours sont remplacees par les valeurs actuelles de la table. 

rem Codel3-03 . odt bibli : ModifTable2 Modulel 
Option Explicit 

Global Voi rEvenements As Boolean 

' Evenement du bouton Afficher les evenements : Changement d'etat 
Sub TracerLesEvenements(evt As Object) 
Voi rEvenements = (evt. Selected = 1) 
End Sub 



' Evenement sur l'objet formulaire : Avant 1 'operation d ' enregi strement 
' renvoie True pour accepter, False pour refuser le changement 
Function AvantOperation(evt As Object) As Boolean 
if Voi rEvenements then 
AvantOperation = (MsgBox("Source : " & evt. Source. ImplementationName 

& chr(13) & "Approuvez-vous cette modification ?", 4, 

"Avant operation d ' enregi strement") = 6) 

el se 

AvantOperation = True 
end if 
End Function 

' Evenement sur l'objet formulaire : Avant le changement d ' enregi strement 
' renvoie True pour accepter, False pour refuser le changement 
Function AvantDeplacement(evt As Object) As Boolean 
if Voi rEvenements then 
AvantDeplacement = (MsgBox("Approuvez-vous ce deplacement ?", 4, _ 
"Avant changement d ' enregi strement") = 6) 

el se 

AvantDeplacement = True 
end if 
End Function 
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Nous avons utilise une variable globale afin de memoriser son etat entre deux lance- 
ments de macro provoques par les evenements de formulaire. Initialement, cette 
variable a la valeur Fal se, ce qui conduit les gestionnaires d'evenements a ne rien 
faire. Le bouton Afficher les evenements est un bouton a bascule. Sur son evenement 
Changement d'etat la macro Trace rLesEvenements est executee. La propriete 
Selected de l'objet evenement reflete alors l'etat atteint par le bouton : 0 pour le 
bouton releve et 1 pour le bouton enfonce. La variable globale prend la valeur True si 
le bouton est enfonce. 

Dans l'onglet Evenements du panneau Proprietes du formulaire, nous avons intercepte 
les evenements : 

• Avant l'operation d'enregistrement ; 

• Avant le changement d'enregistrement. 

Ces deux evenements peuvent etre rejetes (la documentation dit peu elegamment 
« veto-ise »). Nous les traitons done par deux fonctions a resultat de type Boolean. Si 
l'affichage des evenements n'est pas active, 1' evenement est approuve. Si l'affichage 
des evenements est active, un message demandant l'approbation est affiche. Selon le 
resultat du MsgBox, 1' evenement est approuve ou non. Un veritable programme pour- 
rait effectuer des controles de validite avant d'autoriser un evenement. 

Appuyez maintenant le bouton Afficher les evenements. Effectuez une modification et 
actionnez le bouton Enregistrer la saisie. Vous constaterez que deux evenements du 
meme type sont declenches, par un controleur et par l'objet formulaire. 

Effectuez une modification et passez a un autre enregistrement : trois evenements 
apparaissent, deux pour la modification et un pour le changement d'enregistrement. 

En conclusion, la gestion des evenements est assez delicate et le codage doit tenir 
compte des differents cas possibles. 



Ajouter des controles par programme 

Dans certains cas, il n'est pas possible de connaitre a la conception le nombre de con- 
troles dont on aura besoin dans un document formulaire. II est alors necessaire 
d'ajouter ces controles par programme. Ce travail est assez complexe et necessite une 
bonne connaissance de l'API et sa documentation. Avant de l'entreprendre, refle- 
chissez bien a vos besoins. Peut-etre qu'une autre approche du probleme permettrait 
de concevoir un formulaire fixe, bien plus simple a mettre au point. 

Nous allons partir d'un document formulaire existant, comportant un objet formu- 
laire nomme Questionnaire, avec un controle etiquette et un controle bouton qui 
declenche une macro. Cette derniere va creer : 
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• un controle Zone de texte ; 

• un controle Zone numerique ; 

• un controle Bouton dont le declenchement lance une macro existante dans le 
document. 

Nous verrons aussi comment supprimer ces controles. Le codage se compose des 
routines : 

• AjouterControl es, appelee par le bouton pre-existant sur le formulaire ; 

• InsererControle, qui facilite l'insertion de chaque controle ; 

• Suppn'merAutoControles, qui supprime les controles crees dynamiquement ; 

• rei ni ti al i serControl esAuto, qui sera declenche quand on appuie sur le bouton 
insere. 

Void la routine principale : 

rem Codel3-08 . odt bibli : Standard Modulel 
Option Explicit 

Sub AjouterControl es () ' declenche par le bouton "Ajouter" 

Dim monDocument As Object, 1 eFormul ai re As Object, maPage As Object 

Dim Ctrl As Object, p As Long 

monDocument = Thi sComponent 
maPage = monDocument . DrawPage 

1 eFormul aire = maPage . Forms . getByName("Questi onnai re") 
SupprimerAutoControles(leFormulai re, maPage) 

ct rl = c reateUnoServi ce ("com . sun . star . form . component . TextFi el d") 
Ctrl .Name = "info 1" 

Ctrl. Tag = "Auto"' sert a reperer les controles ajoutes 
1 eFormul ai re. insertByIndex(l eFormul ai re . Count , Ctrl ) 

' Largeur 20mm, Hauteur 10 mm, dans la page 5cm a droite et 12cm en bas 
insererControle(monDocument, Ctrl, 2000, 1000, 5000, 12000) 

Ctrl = c reateUnoServi ce ("com . sun . star . form . component . NumericFiel d") 
Ctrl .Name = "info 2" 
Ctrl .Tag = "Auto" 

Ctrl .DecimalAccuracy = 3 ' afficher trois decimales 
Ctrl .ValueMin = -10.0 
Ctrl .ValueMax = 15. 3 
Ctrl .ValueStep =0.1 
Ctrl .DefaultValue = 2.718 

Ctrl. Spin = True ' presentation en forme "compteur" 
1 eFormul ai re . i nsertByIndex(l eFormul ai re . Count , Ctrl) 

' Largeur 20mm, Hauteur 10 mm, dans la page 8cm a droite et 12cm en bas 
insererControle(monDocument, Ctrl, 2000, 1000, 8000, 12000) 
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ct rl = createUnoSe rvi ce ( "com . sun . star . form . component . CommandButton") 

Ctrl. Name = "btn Rempl i ssage" 
Ctrl .Label = "Rempl ir" 

Ctrl .Tag = "Auto" ' sert a reperer les controles ajoutes 

p = leFormulai re. Count ' position de ce controle dans la collection 

1 eFormul ai re . i nsertByIndex(p , Ctrl ) 

' Largeur 26mm, Hauteur 10 mm, dans la page 11cm a droite et 12cm en bas 

insererControle(monDocument, Ctrl, 2600, 1000, 11000, 12000) 

' affecter un traitement a l'evenement "Lors du decl enchement" 

Dim evt As New com. sun. star .script. ScriptEventDescriptor 

evt.ListenerType = "XActionLi stener" 

evt . EventMethod = "acti onPerformed" 

evt.ScriptType = "Script" ' plus general que "Basic" 

evt.ScriptCode = "vnd . sun . star . scri pt : " & _ 

"Standard. Modul el. rei ni ti al i serControl esAuto" & _ 

"?1 anguage=Basi c&l ocati on=document" 
leFormulaire. registerScriptEvent(p, evt) ' affectation au controle 
End Sub 

La routine commence par supprimer les controles eventuellement crees par une exe- 
cution precedente ; nous la detaillerons plus loin. 

Le service com. sun. star. form. component. TextField fournit le modele d'un con- 
trole de Zone de texte. Pour d'autres types de controles, vous devrez utiliser le service 
adequat parmi ceux listes dans la documentation de l'API, a la page 
com. sun. star. form. component. Nous lui donnons un nom interne (propriete Name), 
et nous utilisons la propriete Tag pour noter qu'il s'agit d'un controle cree 
automatiquement ; cela nous servira pour le retrouver quand on voudra le supprimer. 

Ce modele de controle est insere dans la collection de l'objet formulaire, en le mettant a 
la fin de la liste. Puis, nous appelons la routine insererControle en lui transmettant 
notamment les dimensions et la position que devra prendre le controle dans la page. 

rem Codel3-08.odt bibli : Standard Modul el 

Sub insererControle(monDocument As Object, Ctrl As Object, _ 

L As Long, H As Long, X As Long, Y As Long) 
Dim formeCtrl As Object, monTexte As Object, monCurseur As Object 
Dim dimensionsForme As New com. sun. star. awt. Size 
Dim positionForme As New com. sun. star. awt. Point 

monTexte = monDocument .Text 
monCurseur = monTexte . createTextCursor 

formeCtrl = monDocument . createInstance("com . sun . star . drawi ng . Control Shape") 
formeCtrl .Control = Ctrl ' relier la forme au modele du controle 
dimensionsForme. Width = L 
dimensionsForme. Height = H 
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positionForme.x = X 
positionForme.y = Y 
formeCtrl . Si ze = dimensionsForme 

formeCtrl . AnchorType = com. sun. star. text. TextContentAnchorType.AT_PAGE 
monTexte. insertTextContentCmonCurseur , formeCtrl, False) 

formeCtrl . Position = positionForme 
End Sub 

Pour inserer un controle de formulaire, nous devons creer la forme (son dessin) qui 
sera sa partie visible. On retrouve la methode d'insertion d'une forme dans un docu- 
ment Writer (voir a ce sujet le chapitre 8). Ici le type de forme est toujours 
Control Shape. La partie specifique est l'affectation de l'objet modele du controle a la 
propriete Control de la forme. Elle doit etre realisee avant l'insertion effective de la 
forme dans la page de dessin. 

Revenons a la routine principale. Le meme principe est employe pour aj outer le con- 
trole de Zone numerique. On a initialise quelques-unes des proprietes que Ton regie 
d'ordinaire par le panneau Proprietes. Le document PropsFormulai re.ods disponible 
aussi dans le Zip telechargeable vous sera tres utile pour trouver les proprietes de 
chaque type de controle. 

Puis nous inserons le controle bouton. Ici, nous devons affecter une routine a l'eve- 
nement lors du declenchement. Pour cela, nous avons besoin d'une structure 
com. sun. star . scri pt .Scri ptEventDescri ptor dont nous allons remplir : 

• ListenerType avec le nom de l'interface responsable de cet evenement (et even- 
tuellement d'autres evenements). 

• EventMethod avec le nom de l'evenement, lu dans la documentation API a la page 
decrivant l'interface. 

• ScriptType avec le texte "Script" . Ceci nous permet d'appeler un des langages 
de script supportes, Basic, Python, JavaScript, etc. Ceci est plus general que 
l'ancienne valeur "StarBasi c", qui est limitee aux macros Basic. 

• ScriptCode avec un texte complexe (ici reparti sur plusieurs lignes), qui est une 
URL dont la structure depend du langage de script appele. Vous y retrouvez les 
noms de la bibliotheque, du module, et de la routine appelee. 

Pour finir, le traitement est affecte a l'evenement du controle en employant la 
methode regi sterScri ptEvent de l'objet formulaire. Le premier argument est le 
rang du controle dans la collection de l'objet formulaire (c'est la raison pour laquelle 
nous l'avions memorise dans la variable p). 

Connaitre les valeurs a mettre dans la structure Scri ptEventDescri ptor necessite 
une tres bonne connaissance de l'API et sa documentation, et comporte un gros 
risque d'erreur. Une astuce consiste a creer manuellement sur un document separe un 
controle du type souhaite, lui affecter manuellement un script sur un evenement, et 
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visualiser le contenu de cette structure avec l'outil Xray. C'est ce que fait la macro 
Voi rEvenementsTraitesParControles du Module2. Nous ne la decrirons pas, elle est 
facile a adapter sur un autre document. 

Comment supprimer des controles de formulaire ? Pour notre exemple nous avons 
cree une routine qui supprime tous les controles dont la propriete Tag vaut "Auto", 
done ceux que nous avons crees avec une telle valeur. 

rem Codel3-08 . odt bibli : Standard Modulel 

Sub SupprimerAutoControles(leFormulai re As Object, maPage As Object) 
Dim Ctrl As Object, formeCtrl As Object, x As Long, suppr As Boolean 

suppr = False 
x = 0 

Do While x < leFormulai re. Count 
Ctrl = leFormulai re(x) 
if Ctrl .Tag = "Auto" then 

formeCtrl = FindCtrlShapeByName(maPage , leFormulai re. Name, Ctrl. Name) 
if not IsNul 1 (formeCtrl ) then 

maPage. remove(formeCtrl) ' ceci enleve aussi le Ctrl du formulaire 
suppr = True 
x = -1 
end if 
end if 
x = x +1 
Loop 

if suppr then msgBox("Les controles ""Auto"" ont ete supprimes") 
End Sub 

La routine balaie tous les controles de la collection de l'objet formulaire. Pour ceux ayant 
la valeur "Auto", elle retrouve la forme associee avec la routine utilitaire 
Fi ndCtrl ShapeByName que nous avons decrite au debut de ce chapitre. Elle est recopiee 
dans le module Utilitaires du document exemple. Si la forme est retrouvee, elle est sup- 
primee de la page de dessin avec la methode remove de la page, comme toute forme de 
dessin. Sauf que cette suppression entraine en interne la suppression du controle associe, 
done il y a un impact sur la collection de controles. Notez la maniere dont le balayage de 
la collection s'effectue : apres chaque suppression, le balayage reprend depuis le debut. 
Ceci fonctionne meme si les controles sont re-ordonnes par l'objet collection. 



Les documents integres dans un document Base 

Le document Base permet de memoriser un ou plusieurs rapports (aussi appeles 
etats) et documents formulaires, sous forme de sous-documents. Les documents for- 
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mulaires integres sont obligatoirement de type Writer, alors qu'un formulaire separe 
peut etre un document Writer, Calc, Draw, ou Impress. 

Les macros dans un document Base 

Jusqu'a la version 3.0 il n'etait pas possible de mettre des macros dans un document 
Base. Pour contourner cette limitation, on avait deux possibilites : 

• Soit declarer les macros dans Mes macros, ce qui compliquait la portabilite d'un 
ordinateur a l'autre. 

• Soit declarer les macros dans un formulaire integre au document Base. On obte- 
nait alors systematiquement un message d'avertissement a chaque ouverture du 
formulaire, car cette methode n'etait pas vraiment prevue. 

A partir de la version 3.1 les macros ou les scripts d'un des langages supportes peu- 
vent etre stockes dans le document Base lui-meme, mais pas dans un sous-document 
de Base. Ceci necessite de sauvegarder le document Base au format ODF 1.2. 
L'ancienne methode, consistant a ajouter des macros dans un sous-document, ne 
devrait plus etre employee. Notons qu'un assistant de conversion est prevu pour les 
anciens documents. 

On peut maintenant affecter une macro a un evenement concernant un document 
formulaire, par exemple a l'ouverture de celui-ci. Le formulaire etant en mode edi- 
tion, ouvrez le menu Outils>Personnaliser>Evenements. 

Dans le document Base lui-meme, on dispose des evenements Sous-document charge 
et Sous-document ferme, declenches lors de l'ouverture ou de la fermeture de tout 
sous-document, meme en mode edition. Le tableau 13-4 presente les proprietes de 
l'objet transmis avec l'evenement (evt dans nos exemples). Elles ne donnent pas 
acces au sous-document lui-meme. 

Tableau 13-4 Proprietes d'evenement de sous-document 



EventName 


Stri ng 


Nom de l'evenement : OnSubComponentOpened ou 
OnSubComponentClosed 


Source 


Object 


Le document Base pere. 


Vi ewControl 1 er 


Object 


Le controleur en charge de I'affichage du sous-document 


Supplement 


Object 


A l'ouverture, la fenetre (frame) du sous-document. 
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Ouvrir un formulaire d'un document Base 



Ouvrir depuis un autre document que Base 

On peut parfaitement ouvrir un formulaire integre dans un document Base depuis un 
autre document, separe du fichier Base. Ici, nous ouvrons le formulaire Stock des 
produi ts situe dans le document Base BDDi nt . odb, que nous atteignons via sa source 
enregistree. L'affichage prend un certain temps pour aboutir a un formulaire conte- 
nant les donnees de la base. 

rem Codel3-04.odt bibli : SousDocs Modulel 
Option Explicit 

Sub AfficherFormulai reVivant() 
Dim maConnexion As Object 

Dim dbDoc As Object, unFormulR As Object, lesFormulR As Object 
Dim props(O) As New com. sun. star. beans. PropertyValue 
Const nomFormulai re = "Stock des produi ts" 

maConnexion = ConnecterSource("BDDi nt") 
dbDoc = maConnexion. Parent. DatabaseDocument 
lesFormulR = dbDoc. FormDocuments 
if lesFormulR. hasByName(nomFormulai re) then 

props(O) . Name = "Acti veConnection" 

props (0) .Val ue = maConnexion 

unFormulR = lesFormulR. loadComponentFromURL(nomFormulai re, "", 0, props()) 
' unFormul R. pri nt(ArrayO) 
MsgBox("Regardez le formulaire") 
unFormul R . Cur rentControl 1 er . Frame . cl ose(True) 
el se 

MsgBox("Pas de formulaire de ce nom", 16) 
end if 

DeconnecterSource (maConnexion) 
End Sub 

Tout d'abord, nous devons etablir une connexion sur la source de donnees, car le for- 
mulaire doit s'afficher en mode connecte (et non en mode conception). Nous recupe- 
rons le document Base afin d'obtenir la collection de ses formulaires avec la propriete 
FormDocuments (en realite la methode getFormDocuments). Apres avoir verifie qu'un 
formulaire du nom donne existe bien, nous le chargeons avec la methode 
loadComponentFromURL. II s'agit d'une version tres simplifiee de la methode 
employee pour charger un document classique : le premier argument est le nom du 
formulaire, les deux arguments suivants ne sont pas utilises, et le dernier est un 
tableau de PropertyVal ue dont seulement deux proprietes sont utilisables : 
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• Acti veConnecti on contient la connexion deja etablie vers la source de donnees. 

• OpenMode contient une chaine de caracteres, qui est soit "open", soit 
"openDesign" selon qu'on veut respectivement un mode connecte ou un mode 
conception. La valeur par defaut est le mode connecte, aussi nous n'avons pas 
besoin de l'utiliser. 

Vous remarquerez qu'il n'est pas possible de charger le formulaire en mode cache, la 
propriete Hidden etant ignoree. On peut eventuellement imprimer le formulaire, 
comme pour un document ordinaire (voir le chapitre 7), eventuellement apres une 
temporisation. 

La fermeture du formulaire n'est pas evidente, un simple close (True) declencherait 
une exception. Ici, nous fermons en realite la fenetre visible du formulaire, ce qui fer- 
mera le formulaire indirectement. Sans notre instruction de fermeture, il resterait 
affiche jusqu'a sa fermeture par l'utilisateur. 

Ouvrir un formulaire integre depuis son document Base 

Cette partie necessite au moins la version OpenOffice.org 3.1, qui simplifie les 
choses. Nous utiliserons le document BDDint31.odb du Zip telechargeable. 

Ouvrez ce document Base. II comporte des macros dans le document lui-meme. 
Ouvrez le formulaire Stock des produi ts : il comporte deux boutons pour le fermer, 
et deux boutons pour ouvrir le formulaire CI i entel e. Le premier bouton d'ouverture 
intitule Ouvrir Clientele Methode simple declenche la macro ci-dessous : 

rem BDDint31.odb bibli : Standard Modulel 
Option Explicit 

Sub Ouvri rFormulai re(evt As Object) 

Dim dbDoc As Object, lesFormulR As Object, docFormul ai re2 As Object 
Dim bouton As Object, nomFormul ai re As String 

bouton = evt. Source 

nomFormul ai re = bouton. Model .tag 

dbDoc = ThisComponent . Parent 

lesFormulR = dbDoc . FormDocuments 

if 1 esFormul R . hasByName(nomFormul ai re) then 

docFormul ai re2 = lesFormulR. getByName(nomFormul ai re) 

docFormul ai re2 .open 
el se 

MsgBox("Formulai re inconnu : " & nomFormul ai re , 16) 
end if 
End Sub 
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Cette macro est generale : elle ouvre un formulaire dont le nom est recupere dans la 
propriete Tag du modele du bouton (propriete Complement conformation dans le pan- 
neau des proprietes). Ici, la fonction Basic Thi sComponent renvoie le document for- 
mulaire sur lequel nous avons pose le bouton. La propriete Parent du formulaire 
integre nous donne le document Base dont il est un sous-document. Comme nous 
l'avons deja vu, la propriete FormDocuments du document Base nous donne un objet 
collection regroupant tous les sous-documents formulaires. La methode getByName 
(introduite avec la version 3.1) nous renvoie un objet qui n'est pas vraiment le docu- 
ment formulaire, mais qui permet de l'ouvrir par sa methode open. La methode 
openDesign existe aussi, pour ouvrir le formulaire en mode conception. La methode 
close(True) permettrait de le fermer. 

Pour avoir acces au veritable document formulaire, il faut utiliser l'ancienne 
methode, appelee par le deuxieme bouton d'ouverture intitule Ouvrir Clientele 
Methode complexe. 

rem BDDi nt31.odb bibli : Standard Module2 
Option Explicit 

Sub Ouvri rFormulai reBis(evt As Object) 

Dim obj Formul ai rel As Object, docFormul ai re2 As Object 

Dim dbDoc As Object, lesFormulR As Object 

Dim props (0) As New com. sun. star. beans. PropertyVal ue 

Dim bouton As Object, nomFormul ai re As String 

bouton = evt. Source 

nomFormul ai re = bouton .Model .tag 

' acces au document Base sans utiliser Thi sComponent 

objFormulai rel = bouton. Model .Parent 

dbDoc = objFormulai rel. Parent. Parent. Parent 

'dbDoc = Thi sComponent . Parent ' acces simplifie par Thi sComponent 

lesFormulR = dbDoc . FormDocuments 

if lesFormulR.hasByName(nomFormulai re) then 
props (0) .Name = "ActiveConnection" 
props(O) .Value = objFormulai rel. ActiveConnection 
docFormul ai re2 = lesFormulR.loadComponentFromURL(nomFormulai re, _ 
"", 0, propsO) 

el se 

MsgBox("Formulai re inconnu : " & nomFormul ai re , 16) 
end if 
End Sub 

Revoyez la figure 13-2 : nous allons effectuer la remontee depuis un evenement sur un 
controle (ici, le bouton) jusqu'au document Base. Le chemin est indique en pointilles. 
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Comme dans l'exemple precedent, une fois obtenu le document formulaire, sa pro- 
priete Parent nous donne le document Base. Nous aurions pu ecrire, pour vous epater : 

dbDoc = evt. Source. Model .Parent. Parent. Parent. Parent 

La methode d'ouverture reprend l'exemple deja vu avec Codel3-04 . odt, mais ici nous 
utilisons la connexion deja etablie pour le formulaire Stock des produits, actuelle- 
ment ouvert. Ici, contrairement a la methode simplifiee, nous pourrions acceder aux 
controles du formulaire. 

Fermer un formulaire par un bouton 

L'utilisateur peut apprecier de sauver les modifications en cours et fermer le formu- 
laire en actionnant un seul bouton. II suffit que le bouton lance cette macro : 

rem BDDint31.odb bibli : Standard Module2 
Option Explicit 

Sub SauverModifsEtFermerFormulai re(evt As Object) 
Dim obj Formul ai re As Object 
obj Formul ai re = evt . Source . Model . Parent 
obj Formul ai re . updateRow 
StarDesktop . CurrentFrame . cl ose(True) 
End Sub 

Depuis l'objet evenement transmis par Faction sur le bouton, nous remontons a l'objet 
formulaire selon le chemin sur la figure 13-2. Sa methode updateRow permet de prendre 
en compte une ligne actuellement en cours de modification. La fenetre du document 
formulaire est tout simplement la fenetre OpenOffice en cours, que nous fermons. 

Dans le cas oil on veut simplement fermer le formulaire comme si on actionnait la 
case X du coin de la fenetre, il est plus simple de ne pas declencher de macro mais de se 
contenter de remplir les proprietes Action et URL du panneau de proprietes du bouton : 

• Dans le champ Action, choisissez Ouvrir la page web. 

• Dans le champ URL, saisissez . uno : Cl oseWi n. 

Avec cette deuxieme solution si une modification est en cours, OpenOffice deman- 
dera a l'utilisateur s'il veut enregistrer les changements. Les deux manieres de fermer 
sont mises en oeuvre dans le formulaire Stock des produits du document 
BDDint31.odb disponible dans le Zip telechargeable. 
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Obtenir les contrdles d'un formulaire integre 

Nous allons lister les noms des controles de chaque objet formulaire contenu dans un 
document formulaire integre dans le document Base. Dans cet exemple, realise dans 
un document separe, il nous faut dans un premier temps recuperer le sous-formulaire 
correspondant, puis trouver le ou les objets formulaire au sens API, et enfin trouver 
les controles contenus dans chacun de ces objets. 

rem Codel3-04.odt bibli : SousDocs Module2 
Option Explicit 

Sub retrouverControles() 
Dim maConnexion As Object 

Dim dbDoc As Object, unFormulR As Object, lesFormulR As Object 
Dim props(O) As New com. sun. star. beans. PropertyValue 
Const nomFormulai re = "Stock des produits" 

maConnexion = ConnecterSource("BDDi nt") 
dbDoc = maConnexion. Parent. DatabaseDocument 
lesFormulR = dbDoc. FormDocuments 
if lesFormulR. hasByName(nomFormulai re) then 

props(O) . Name = "Acti veConnection" 

props (0) .Val ue = maConnexion 

unFormulR = lesFormulR. loadComponentFromURL(nomFormulai re, "", 0, propsO) 
1 i sterOb j etsFormul ai res(unFormul R . DrawPage . Forms) 

MsgBox("Le document va fermer") 
unFormul R . Cu r rentControl 1 er . Frame . cl ose(True) 
el se 

MsgBox("Pas de formulaire de ce nom", 16) 
end if 

DeconnecterSource (maConnexion) 
End Sub 



Sub listerObjetsFormulaires(lesFormulaires As Object) 

Dim unFormulR As Object, unCtrl As Object, liste As String 

Dim f As Long, k As Long 

for f = 0 to lesFormulai res .Count -1 
unFormulR = lesFormulai res(f) 
liste = "Controles : " & chr(13) 
for k = 0 to unFormulR. Count -1 

unCtrl = unFormul R(k) 

liste = liste & unCtrl. Name & chr(13) 
next 

MsgBox(liste, 0, "Formulaire : " & unFormulR. Name) 

next 
End Sub 
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Nous commencons par afficher le document formulaire en mode connecte. Nous recu- 
perons ensuite l'objet collection des objets formulaires contenus dans le sous-docu- 
ment. Nous avons prevu une boucle, mais vous verrez qu'il n'y a qu'un seul objet formu- 
laire principal. II ne reste plus qua explorer les controles affectes a l'objet formulaire. 

Ouvrir un formulaire en mode conception 

Si nous souhaitons seulement ouvrir un formulaire en mode conception, il n'est pas 
necessaire d'etablir une connexion avec la base de donnees. Le document Base est en 
realite ouvert en mode cache, et il sera ferme a la fermeture du formulaire. Ici, nous 
laissons a l'utilisateur le soin de fermer le formulaire. 

rem Codel3-04.odt bibli : SousDocs Module3 
Option Explicit 

Sub AfficherFormulai reModeConception() 

Dim dbContexte As Object, maSource As Object 

Dim dbDoc As Object, unFormulR As Object, lesFormulR As Object 

Dim props(O) As New com. sun. star. beans. PropertyVal ue 

Const nomFormulai re = "Stock des produits" 

dbContexte = CreateUnoServi ce("com . sun . star . sdb . DatabaseContext") 

maSource = dbContexte. getByName("BDDint") 

dbDoc = maSource. DatabaseDocument 

lesFormulR = dbDoc . FormDocuments 

if lesFormulR. hasByName(nomFormulai re) then 

props(O) .Name = "OpenMode" 

props(O) .Value = "openDesign" 

unFormulR = lesFormulR. loadComponentFromURL(nomFormulai re, "", 0, props()) 
el se 

MsgBox("Pas de formulaire de ce nom", 16) 
end if 
End Sub 



Ouvrir un rapport d'un document Base 

Ouvrir un rapport integre dans le document Base suit exactement le meme principe 
que pour un formulaire integre. Au lieu de la propriete FormDocuments, on utilise la 
propriete ReportDocuments. Le document Codel3-04.odt du Zip telechargeable con- 
tient un exemple, au Module4 de la bibliotheque SousDocs. Le formulaire Stock des 
produi ts du document BDDi nt31 . odb comporte un bouton pour ouvrir un rapport. 
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Conclusion 

Les documents formulaires comportent des controles tres similaires a ceux des dialo- 
gues, lis peuvent soit etre utilises independamment d'une base de donnees, soit per- 
mettre a l'utilisateur de manipuler la base de donnees. Les formulaires integres sont 
plus pratiques pour l'utilisateur mais plus complexes pour le programmeur. Ce cha- 
pitre clot le traitement des sources de donnees au travers de l'API. 

Nous exposerons au chapitre suivant une partie de l'API dans un contexte hors docu- 
ment bureautique, illustrant ainsi la richesse et la puissance applicative qui sont a la 
disposition du developpeur par le biais des macros. 
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Techniques avancees 
pour le poste de travail 



Ce chapitre presente des manipulations et des macros utilitaires faisant appel a des 
aspects avances de la programmation OpenOffice.org. Ces methodes peu connues 
trouveront leur utilite dans la plupart des projets d'applications d'envergure utilisant 
l'API d'OpenOffice.org comme un veritable environnement de developpement dans 
lequel de nombreux outils sont disponibles. 



Les repertoires d installation 

Disponible sous differents systemes d'exploitation, OpenOffice.org permet a l'utilisa- 
teur de choisir le nom du repertoire principal d'installation. De plus, les donnees de 
chaque utilisateur sont memorisees dans des repertoires particuliers, selon le systeme 
d'exploitation. L'organisation des repertoires evoluant avec les versions d'Open- 
Office.org, nous decrivons plus loin des services permettant de connaitre l'adresse 
reelle d'une categorie d'informations. Le menu Outils>Options>OpenOffice.org>Chemins 
permet de modifier certains de ces repertoires. 
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La structure en couches d OpenOffice.org 3 



La version 3 d'OpenOffice.org a introduit une installation en trois couches des don- 
nees propres a l'application : 

• La couche la plus basse est l'URE (UNO Runtime Environment), qui implemente 
le concept UNO. 

• La couche intermediate, Basis, contient l'essentiel des fonctionnalites Open- 
Office.org. 

• La couche externe personnalise le produit commercial (OpenOffice.org, 
BrOffice, StarOffice, etc). Plusieurs couches externes pourraient etre installees en 
parallele et utiliser en meme temps les couches inferieures. 

Cette organisation explique pourquoi on trouve dans l'arborescence d'installation 
d'OpenOffice.org un dossier Basis/, un dossier URE/, et des sous-dossiers en double 
exemplaires comme program/ et share/. 



Le service PathSettings connait toutes les adresses de repertoires utilises par la ver- 
sion d'OpenOffice.org qui execute la macro. Son usage est tres simple : d'abord 
obtenir un acces au service, puis utiliser ses proprietes, qui sont toutes des chaines de 
caracteres listant un ou plusieurs repertoires. S'il existe plusieurs repertoires pour une 
propriete, ils sont separes par un point-virgule. Chaque repertoire est sous forme 
d'URL, sans caractere / final. Un repertoire indique peut ne pas exister, selon la con- 
figuration. 

Void comment lister les repertoires des macros Basic : 

rem Codel4-01 . odt bibli : Chemins Modulel 
Option Explicit 

Sub UtiliserPathSettingsO 

Dim ps As Object, repertoires As Variant, r As String 
ps = CreateUnoService("com. sun. star. util .PathSettings") 
repertoires = spl it(ps . Basic , ";") 
For Each r in repertoires 

MsgBox(r, 0, "URL de repertoire macros Basic") 
Next 
End Sub 

Nous avons utilise la propriete Basic de l'objet fourni par le service PathSettings. 
La fonction spl i t decoupe la chaine de caracteres obtenue a chaque point-virgule et 
cree un tableau de chaines, une par repertoire. La boucle For Each explore ce tableau 
et affiche chaque URL. Les proprietes disponibles sont listees au tableau 14-1. 



Le service PathSettings 
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Tableau 14-1 Proprietes de PathSettings 



Addi n 


Utilise par les anciens add-ins de Calc. 


AutoCorrect 


Configuration pour I'Autocorrection. 


AutoText 


Modules de I'AutoTexte. 


Backup 


Copies de sauvegarde. 


Basi c 


Fichiers contenant les macros Basic et les dialogues. 


Bi tmap 


Anciennes icones pour les barres d'outils. 


Conf i g 


Fichiers de configuration de I'application. 


Dictionary 


Dictionnaires. 


Favorite 


Favoris. 


Filter 


Filtres. Semble non utilise. 


Gal 1 ery 


Fichiers de la Galerie. 


Graphic 


Fichiers images. 


Help 


Fichiers d'aide. 


Linguistic 


Fichiers de dictionnaires 


Modules 


Modules de programme. 


Palette 


Fichiers de palettes de couleurs. 


PI ugi n 


Fichiers plug-ins. 


Storage 


Donnees utilisateur concernant e-mail, FTP, etc. 


Temp 


Repertoire de donnees temporaires. 


Template 


Modeles de documents. 


UlConfig 


Fichiers pour configurer I'interface utilisateur. 


UserConfig 


Repertoire des configurations utilisateur. 


Work 


Repertoire de travail. 



Le service PathSubstitution 

Le service PathSubstitution offre d'autres possibilites : il remplace un mot-cle dans 
une chaine de caracteres par la valeur correspondante, en principe un chemin. La 
chaine de caracteres doit etre compatible avec un format URL, car le resultat sera 
une URL. Ainsi, cette macro ecrit un fichier de travail dans le repertoire dedie aux 
fichiers temporaires : 



rem Codel4-01 . odt bibli : Chemins Module2 
Option Explicit 
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Sub SubstituerCheminO 

Dim f i chTempo As String 

Dim fl As Integer, ps As Object 

ps = CreateUnoServiceC'com. sun. star. util . PathSubstitution") 

fi chTempo = "$(temp)/monFi ch$12345x . html " 

fichTempo = ps.substituteVariables(fichTempo, false) 

fl = FreeFile 

' ecrire le fichier en ecrasant un eventuel fichier existant 
Open fichTempo for Output As fl 
print #fl, "Bonjour tout le monde!" 
Close #fl 
End Sub 

Le mot-cle $(temp) represente le repertoire utilise pour les fichiers temporaires. La 
fonction substituteVariables du service va remplacer tous les mots-cles existant 
dans la chaine de caracteres en premier argument. Lorsque le deuxieme parametre 
vaut true, une erreur sera declenchee en cas d'impossibilite de substituer. La fonc- 
tion renvoie la chaine de caracteres resultant de la substitution. Nous utilisons 
l'adresse obtenue pour creer le fichier et le remplir. 

Linteret de ce service PathSubstitution est de rendre independante du systeme 
d'exploitation une adresse URL comportant un substituant : la conversion inverse 
donnera une veritable URL correspondant a l'installation propre au systeme 
d'exploitation en cours, qu'il soit MS-Windows, Linux, ou Mac OS. 

Le tableau 14-2 liste les variables de substitution disponibles. Le contenu d'une 
variable est renvoye par la fonction getSubsti tuteVari abl eVal ue : 

Dim ps As Object, si As String 

ps = CreateUnoServiceC'com. sun. star. util .PathSubstitution") 
si = ps .getSubstituteVariableValue("$(work)") 

MsgBox(sl) 



Tableau 14-2 Variables de substitution 




$(inst) 
S(insturl) 


Repertoire d'installation de la couche Basis. 


$(prog) 
S(progurl) 


Repertoire du programme OpenOffice.org dans la couche Basis. 


S(brandbaseurl) 


Repertoire de la couche commerciale. 


$(user) 

S(userdataurl) 


Repertoire user propre a I'utilisateur. 


$(work) 


Repertoire de travail. 
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Tableau 14-2 Variables de substitution (suite) 


Variable Signification 


$(home) 


Repertoire de donnees de I'utilisateur. 


$(temp) 


Repertoire des fichiers temporaires. 


$(path) 


Contenu de la variable d'environnement PATH. Les repertoires sont separes par un 
point-virgule. 


$(lang) 


Numero de pays de la langue de I'interface utilisateur (France=33, USA=01). 


$(langid) 


Numero de code de langue de I'interface utilisateur (France=1036). 


$(vl ang) 


Locale de I'interface utilisateur (par exemple fr ou en-US). Voir la definition de 
Locale au chapitre 7. 



II est possible de definir d'autres variables de chemin en ajoutant un fichier 
Substitution.xml dans le repertoire org/openoff ice/Off ice/ de la Registry. Le 
chapitre Office Development Common Application Features>Path Organization du 
Developer's Guide donne plus de details techniques sur les services PathSettings et 
PathSubstitution. 



Repertoires des scripts 

Les macros et scripts de Mes Macros sont memorisees dans des sous-repertoires 
basic/ et Scripts/ des donnees utilisateur, les macros et scripts de Macros Open- 
Office.org sont memorisees dans des sous-repertoires Basis/basic/ et Basis/ 
Scripts/ de l'installation OpenOffice.org. 

A partir de la version 3.0 d'OpenOffice.org, les macros Basic et les scripts des exten- 
sions sont memorisees seulement dans le sous-repertoire user/uno_packages/ ou 
share/uno_packages/, selon que l'extension est installee pour un utilisateur ou pour 
tous les utilisateurs. 

Repertoire d'installation d'une extension 

Chaque extension est physiquement deployee dans un repertoire dont le chemin est 
defini dynamiquement lors de son installation. II est parfois necessaire de connaitre ce 
repertoire afin d'obtenir un des fichiers de l'extension (par exemple une image a affi- 
cher). Rappelons que l'extension est elle-meme une arborescence de sous-repertoires. 

dim sv As Object, repExt As String 
sv = GetDefaultContext.getByName 

("/si ngl etons/com. sun . star . depl oyment . PackagelnformationProvi der") 
repExt = sv.getPackageLocation("org.toto.test3") 
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Nous utilisons un type de service particulier, appele singleton. On l'obtient avec la 
fonction OOoBasic GetDefaultContext et sa methode getByName. Le nom complet 
doit etre ecrit tel quel, et l'instruction est ici repliee sur deux lignes par contrainte 
d'edition. Ce service nous donne l'URL du repertoire avec sa methode 
getPackageLocation qui prend en argument le nom unique de l'extension. Ce nom 
unique doit etre declare dans la section identifier du fichier description.xml de 
l'extension. Avec l'outil Extension Compiler, il s'agit du premier argument de l'ins- 
truction beginDescription. 

La chaine de caracteres obtenue est un chemin tres long, se terminant par un reper- 
toire qui a le nom du fichier extension, sans caractere / final. II s'agit bien d'un reper- 
toire, et non d'un fichier. 



Modifier la configuration d OpcnOfficc.org 

La configuration d'OpenOffice.org est memorisee dans une base de donnees d'un 
genre assez particulier, appelee base de Registre {Registry, en anglais). Elle 
memorise : 

• la configuration d'OpenOffice.org lui-meme, avec des elements propres a Writer, 
Calc, etc, et des donnees liees aux extensions OpenOffice.org ; 

• la configuration propre a chaque utilisateur, barres d'outils, menus, raccourcis, et 
des donnees liees a ses extensions. 

Ne PAS CONFONDRE Registre et registre 

Notre base de registre n'a rien a voir avec la base de registre MS-Windows. Ce sont deux bases de don- 
nees independantes. 

La configuration effective peut etre considered comme le resultat d'application de 
couches successives de configurations, la couche utilisateur ayant priorite sur la 
couche extension, elle-meme prioritaire sur la couche de l'application. 

Pour acceder a la base de Registre OpenOffice.org, on peut utiliser la fonction 
GetRegi stryKeyContent qui se trouve, avec quelques exemples d'utilisation, dans la 
bibliotheque Tools de Macros OpenOffice.org, module Misc. Nous avons prefere une 
methode qui peut etre appliquee systematiquement pour toute donnee : les macros 
utilitaires du document ExplorateurConfig.ods (qui se trouve dans le Zip telechar- 
geable, dans le dossier consacre a ce chapitre). 
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Pour aller plus loin 

Le Developer's Guide consacre un chapitre a la gestion de configuration : 

► http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Config/ 

Configuration_Management 
Les services essentiels sont : 

• com. sun . star . confi gurati on . Confi gurationProvi der 

• com. sun . star . confi gurati on . Admi ni strati onProvi der 

• com . sun . star . confi gu rati on . Confi gu rati onAccess 

• com . sun . star . confi gu rati on . Confi gu rati onUpdateAccess 



Comment est stockee la base de registre OpenOffice.org ? 

L'information contenue dans la base de Registre est stockee dans des fichiers XML 
d'extension xcu. Un fichierXML ressemble a un fichier HTML : il est lisible en 
clair avec un simple editeur de texte, mais sa structure suit des regies precises, defi- 
nies dans un schema XML. Les schemas XML sont memorises dans des fichiers 
d'extension xcs. 

Emplacements des fichiers xcu 

Les fichiers xcu utilises par OpenOffice.org peuvent se trouver dans differents reper- 
toires (et leurs sous-repertoires). II peut y avoir plus ou moins de fichiers selon la 
configuration effectuee. Nous donnons ici les adresses relatives, pour la version 3.0 
d'OpenOffice.org. 



MS-Windows 

Sous MS-Windows, changez les / en \ dans les adresses relatives que nous indiquons. 



Dans le repertoire d'installation d'OpenOffice.org, les fichiers xcu se trouvent dans 
les arborescences debutant a : 

OpenOf f i ce .org 3/Basi s/share/regi stry/data/ 
OpenOf f i ce . org 3/share/regi stry/data/ 

OpenOf fi ce . org 3/share/uno_packages/ cache/ regi s try/com . sun . star . comp . 
deployment . confi gurati on . PackageRegi stry Backend/ regi stry/data/ 

La derniere adresse, tres longue, correspond aux extensions communes a tous les uti- 
lisateurs. 
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Certaines de ces donnees administratives servent de valeur initiale pour la configura- 
tion d'un nouvel utilisateur. Dans le repertoire des donnees OpenOffice.org propres 
a chaque utilisateur, les fichiers xcu se trouvent dans les arborescences debutant par : 

OpenOffi ce . org/3/user/regi stry/data/ 

OpenOf f i ce . org/3/user/uno_packages/cache/regi st ry/com . sun . star . comp . 
depl oyment . conf i gu rati on . PackageRegi s try Backend/ regi stry/data/ 

La derniere adresse, tres longue, correspond aux extensions installees par l'utilisateur. 
Lorsque l'utilisateur modifie une valeur, ce changement est memorise dans les don- 
nees utilisateur, et vient alors « masquer » la valeur administrative. 

Emplacements des schemas xcs 

La base de Registre ne peut memoriser que des donnees dont la syntaxe est decrite 
dans des fichiers schemas, d'extension xcs. Ces fichiers se trouvent dans le repertoire 
d'installation d'OpenOffice.org, dans l'arborescence debutant par : 

OpenOffi ce .org 3/Basi s/share/regi stry/schema/ 

Si une extension ajoute un fichier de configuration accompagne de son schema, ce 
dernier se trouvera dans le repertoire des executables si 1' extension est installee pour 
tous les utilisateurs : 

OpenOffi ce . org 3/share/uno_packages/cache/regi st ry/com . sun . star . comp . 
depl oyment . confi gurati on . PackageRegi s try Backend/ regi stry/schema/ 

ou bien dans le repertoire des donnees de l'utilisateur si 1' extension est installee pour 
celui-ci seulement : 

OpenOffi ce . org/3/user/uno_packages/cache/regi st ry/com. sun . star . comp . 
depl oyment . confi gu rati on . PackageRegi s try Backend/ regi stry/schema/ 

La hierarchie de la base de Registre 

Lensemble de la base de donnees est organisee dans une hierarchie virtuelle qui 
debute par la sequence /org.openoffice. Le caractere / indique une adresse absolue 
dans la hierarchie. La sequence org.openoffice a ete choisie pour la distinguer 
d'autres hierarchies qui ne seraient pas celle utilisee par OpenOffice.org. 
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La base est repartie sur plusieurs niveaux, par exemple : 

/org . openof f i ce . Of f i ce 

/org . openof f i ce . Of f i ce . UI 

/org . openof f i ce . Of f i ce . UI . Cal cCommands 

A chaque niveau, on peut trouver (ou pas) des donnees, qui sont regroupees sous un 
nom. Un niveau comportant des donnees est un noeud {nodepath, en anglais). 

Un noeud fournit une liste de noms de conteneurs rattaches a ce noeud. Chaque con- 
teneur est lui-meme hierarchise. II peut exposer soit des sous-conteneurs hierar- 
chises, soit des elements terminaux. Dans le chemin de la hierarchie de la base de 
registre, chaque conteneur est ajoute apres un caractere /. Void quelques exemples : 

/org . openof f i ce . Of f i ce . UI/Fi 1 ePi cker 

/org . openof fi ce . Off i ce . UI/Fi 1 ePi cker/Ti meout 

/org . openof fi ce . Of f i ce . UI/Fi 1 terCT assi f i cati on/Gl obal Fi 1 ters 

Les donnees terminales 

Chaque donnee terminale a un nom. Elle peut etre de type simple, ou etre un tableau 
de valeurs d'un type simple. Les types simples possibles sont : 

• stri ng : chaine de caracteres Unicode ; 

• bool ean : valeur binaire ; 

• short : entier sur 16 bits ; 

• i nt : entier sur 32 bits ; 

• 1 ong : entier sur 64 bits ; 

• double : nombre flottant. 

Le type binary est un tableau d'octets. II ne doit pas etre utilise pour memoriser des 
fichiers, car cela ne serait pas efficace. On utilise a la place une chaine de caracteres 
donnant l'adresse URL du fichier concerne. 

Certaines donnees de configuration, par exemple contenant des chaines de caracteres 
a afficher, dependent de la langue utilisee. Le mecanisme de stockage permet de qua- 
lifier une donnee, ou un ensemble de donnees, avec un identifiant de localisation (par 
exemple f r), ce qui permet de memoriser pour la meme donnee des valeurs diffe- 
rentes suivant la langue. 

La lecture du registre OpenOffice.org s'effectue normalement pour une localisation 
particuliere, eventuellement implicite. Cette lecture donne la donnee dont la locali- 
sation correspond au mieux a celle demandee. Par exemple, si nous cherchons une 
donnee dans sa localisation "f r-BE" (francais parle en Belgique) : 
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1 Si la donnee existe avec cette localisation, sa valeur sera recuperee. 

2 Sinon, si elle existe en f r, sa valeur sera recuperee. 

3 Sinon, si elle existe avec une quelconque variante f r-XX, la valeur de la premiere 
variante trouvee sera recuperee. 

4 Sinon, si elle existe en localisation en, sa valeur sera recuperee. 

5 Sinon, n'importe quelle autre localisation fera l'affaire. 

Les routines de l'API utilise par defaut la langue de l'interface utilisateur. 

Contenu d'un fichier de configuration 

Pour lire ces fichiers il est preferable d'utiliser un editeur de texte capable d'effectuer 
la coloration syntaxique du XML et sachant plier/deplier les elements emboites. 
Nous ne citerons que les elements parti culierement significatifs. 

L'element oor: component-data place en debut de fichier contient l'adresse, dans la 
base de Registre, des donnees que ce fichier contient. Elle se compose de deux sous- 
elements, package et name. Le package est l'identite du noeud, le name est le conte- 
neur principal. Void un exemple : 

<oor: component-data xml ns : oor="http ://openof f i ce . org/2001/ regi stry" 
xml ns :xs="http : //www.w3 . org/2001/XMLSchema" xml ns : xsi= 
"http://www.w3 .org/2001/XMLSchema-i nstance" 
xml ns : i nstal 1 ="http : //openof f i ce . org/2004/i nstal 1 ati on" 
oor : name="Compati bi 1 i ty" oor : package="org . openof f i ce . Of f i ce"> 

Dans cet exemple, le conteneur a done pour adresse complete : 
/org . openof f i ce . Of f i ce/Compati bi 1 i ty 

Dans la suite du fichier, on trouvera en general au moins un sous-conteneur, identifie 
par son nom, et annonce par un element node. Voici un exemple : 

<node oor : name="Wri terCompati bi 1 i tyVersi on"> 

Dans un conteneur terminal, on trouvera au moins une propriete, identifiee par son 
nom et son type de donnees, et annoncee par un element prop. En voici un exemple : 

<prop oor :name="00oll" oor : type="xs : stri ng"> 
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Cette propriete aura en general une valeur, annoncee par un element value, par 
exemple : 

<val ue>OpenOf f i ce . org 1 . l</val ue> 

Les elements sont en general emboites. Les espaces et indentations entre elements 
n'ont pas de signification. L'ordre des sous-elements d'un element est quelconque. 

Le nom du fichier est totalement sans importance, de meme que son emplacement dans 
une des arborescences. Soulignons que seul compte le contenu du fichier. Les donnees 
d'un conteneur d'un noeud de la base de Registre peuvent etre physiquement reparties 
dans differents fichiers, a differents endroits des arborescences. C'est ce qui permet de 
modifier une configuration pour un utilisateur, ou par l'installation d'une extension, 
simplement en ajoutant un fichier qui modifie l'existant ou ajoute des donnees. 

Modifier une configuration par fichier 

II est possible de creer un fichier xcu qui se base sur la structure d'un fichier existant, 
et qui se limite a changer une ou plusieurs valeurs dans un noeud. Ce nouveau fichier 
sera installe en creant une extension simple. Lavantage est double : d'une part l'ins- 
tallation est facile, d'autre par l'annulation des modifications se fait par desinstalla- 
tion de l'extension. Reportez vous a la page (en anglais) pour plus de details : 

http://wiki.services.openoffice.org/wiki/Non-code_extensions 

Une extension peut necessiter de memoriser des donnees de configuration, parfois 
complexes, propres a l'utilisateur de l'extension. Pour ce faire, l'extension comportera 
un fichier xcu specifique, accompagne de son fichier schema xcs. 

Explorer la base de registre 

Bizarrement, il ne semble pas exister de methode API pour explorer systematique- 
ment la base de registre OpenOffice.org. II est necessaire de partir d'un noeud connu. 
Nous avons vu plus haut comment trouver des noeuds a partir de fichiers xcu dans les 
repertoires OpenOffice.org. 

LAPI permet d'effectuer une recherche recursive sur le contenu d'un noeud. Voici 
comment la parametrer dans le document ExplorateurConfig.ods du Zip 
telechargeable : 

1 Cliquez sur le bouton de la feuille Sommai re du document. Un panneau de dialo- 
gue s'ouvre. 

2 Choisissez un noeud dans la liste, ou indiquez un autre noeud. 

3 Precisez eventuellement la localisation, par defaut ce sera la langue de l'interface 
utilisateur. 
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4 Indiquez la zone de configuration a lire, utilisateur (habituellement) ou adminis- 
tration. 

La feuille Resultats liste chaque element terminal trouve, avec son type et sa valeur. 
Le type est indique par son equivalent Basic. Certains nceuds donnent plusieurs mil- 
liers de lignes. Pour un meme noeud, le nombre de lignes de resultat differe selon la 
vision utilisateur ou administration. 

Lire une valeur de la base de registre 

Connaissant le chemin hierarchique d'une donnee (colonne A de la feuille Resultats 
du document ExplorateurConfig.ods) et le nom de la donnee (colonne B de la 
meme feuille), il est possible d'obtenir la valeur de cette donnee. Le module Utiles 
dans la bibliotheque Standard du document offre deux routines : 

• ReadOOoUserData pour lire une donnee dans la zone de donnees utilisateur, 

• ReadOooAdmi ni strati veData pour lire une donnee dans la zone de donnees 
administrative. Ceci est rarement necessaire. 

Ces routines modifient deux variables passees en arguments : un indicateur d'echec 
ou de succes, et la valeur obtenue. Vous devez utiliser une variable Variant pour 
recuperer le resultat, celui-ci pouvant etre Empty. La macro RecuperationDeValeur 
(bibliotheque Standard, Module3) donne plusieurs exemples. 

Modifier une valeur de la base de registre 

De maniere similaire a la lecture, le module Uti 1 es dans la bibliotheque Standard du 
document ExplorateurConfig.ods offre deux routines : 

• WriteOOoUserData pour modifier une donnee dans la zone de donnees 
utilisateur ; 

• WriteOooAdmi ni strati veData pour modifier une donnee dans la zone de donnees 
administrative. Vous devez disposer de droits d'acces suffisants sur les repertoires 
et fichiers a modifier. 

La variable passee en argument de numero d'erreur est modifiee selon le resultat 
obtenu. La macro ModificationDeValeur (bibliotheque Standard, Module4) donne 
plusieurs exemples. 

OpenOffice.org utilise abondamment un cache des valeurs de registre. Une modifi- 
cation de configuration ne sera pas toujours refletee dans l'interface utilisateur (par 
exemple dans les panneaux du menu Outils>0ptions), il faudra peut-etre redemarrer 
OpenOffice.org (voir Tissue 93203). De plus, certaines options de defaut peuvent 
etre remplacees par celles utilisees dans le document en cours, ou dans le modele qui 
a cree le document, par exemple Outils>Options>Calc>Calculer>Nombre de decimales. 
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Gerer les fichiers depuis l'API 

Le service SimpleFileAccess offre des fonctions de gestion de fichiers (effacer un 
fichier, le copier, etc.) qui sont redondantes avec celles de Basic. Neanmoins, il 
apporte aussi des possibilities complementaires. La gestion de fichier par l'API 
emploie le principe logiciel des flux (stream, en anglais). 

Ecrire un fichier binaire 

Nous allons creer un fichier, octet par octet. Adaptez a votre configuration le chemin 
du fichier indique par la constante nomFichl, nous l'utiliserons aussi pour lire le 
fichier. 

rem Codel4-01 . odt bibli : Fichiers Modulel 
Option Explicit 

Public Const nomFichl = "C:\Docs 0pen0ffice\essai002.bin" 
Sub Ecri reFi chi erBi nai re() 

Dim fl As Object, flux As Object, unPaquet(4) As Integer 

if FileExists(nomFichl) then Kill (nomFi chl) 

' constitution d'un paquet d'octets a ecrire 

unPaquet(O) = extSigne(78) 

unPaquet(l) = extSi gne(lll) 

unPaquet(2) = extSigne(255) 

unPaquet(3) = extSigne(O) 

unPaquet(4) = extSi gne(200) 

fl = createllnoServi ce("com. sun. star. ucb.SimpleFileAccess") 

flux = fl.openFileWrite(convertToURL(nomFichl)) 

fl ux.writeBytes(unPaquetO) 

f 1 ux . fl ush 

flux.closeOutput 

End Sub 

' etend le bit signe de l'octet sur tout l'entier Integer 
Function extSigne( unOctet As Integer) As Integer 
if unOctet < 128 then 

extSigne = unOctet 
else ' etendre le bit signe (valeur 1) sur 8 bits a gauche 

extSigne = -256 or unOctet ' attention : OU binaire 
end if 
End Function 
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Avec l'API, ouvrir un fichier en ecriture ne supprime pas un fichier existant : les 
octets non recrits sont conserves. Dans notre cas, nous preferons supprimer un even- 
tuel fichier existant avec l'instruction OOoBasic Ki 11 . 

Le service SimpleFileAccess permet d'ouvrir le fichier en ecriture avec sa methode 
openFileWrite, qui nous donne un objet de flux servant a l'ecriture. La methode 
wn'teBytes ecrit les octets qui lui sont transmis par un tableau, dans l'ordre croissant 
de l'index. Bien que le type Byte ait ete introduit dans OOoBasic, il n'est en fait pas 
utilisable ici car l'interfacage avec l'API necessite des valeurs signees, entre -128 et 
+ 127. Nous devons utiliser un tableau de valeurs Integer (16 bits). Afin de conserver 
l'habitude de manipuler des octets non signes (valeur entre 0 et 255) nous utilisons 
une fonction utilitaire extSigne qui realise le transcodage en etendant vers la gauche 
le bit signe de l'octet. Dans un veritable programme, la methode writeBytes serait 
utilisee autant de fois que necessaire, en employant un tableau dont la taille peut 
varier selon les besoins. 

La methode flush sert a garantir que le tampon a bien ete ecrit physiquement avant 
de fermer le fichier par la methode cl oseOutput. 

Lire un fichier binaire 

Nous allons relire par macro, et octet par octet, le fichier ecrit precedemment. 

rem Codel4-01.odt bibli : Fichiers Module2 
Option Explicit 

Sub Li reFi chi erBi nai re() 

Dim fl As Object, flux As Object, unPaquetO As Integer 
Dim x As Long, nbOct As Long 

fl = createUnoService("com. sun. star. ucb. SimpleFileAccess") 
flux = fl.openFileRead(convertToURL(nomFichl)) 
nbOct = flux.readBytes(unPaquet() , 100) 
for x = 0 to nbOct-1 

print (unPaquet(x) and 255) 
next 

nbOct = flux.readBytes(unPaquet() , 100) 
MsgBox("Reste a lire : " & nbOct & " octets") 
flux.closelnput 
End Sub 

On ouvre le fichier en lecture avec la methode openFileRead du flux. 

La methode readBytes remplit le tableau transmis en premier argument. Le 
deuxieme argument est le nombre maximum d'octets que Ton souhaite lire. Le 
resultat de la methode est le nombre d'octets effectivement lus, qui peut etre inferieur 
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si la fin du fichier a ete atteinte. Dans notre cas, tout le fichier est lu d'un seul coup. 
Pour afficher chaque octet sous une forme naturelle, il est necessaire de le trans- 
former en valeur positive par un ET logique avec la valeur 255 (en valeur 
hexadecimale : OOFF). La deuxieme instruction readBytes confirme que tout le 
fichier a ete lu, car elle renvoie une valeur nulle. 

Le fichier est ferme par la methode closelnput, puisqu'il a ete ouvert en lecture. 

Signalons l'existence de la methode skipBytes de l'objet stream, qui sert a avancer 
dans le fichier du nombre d'octets indique en argument. Ceci est utile pour sauter 
des zones que Ton sait sans interet pour le travail envisage. 

st.skipByte(200) ' sauter les 200 octets suivants 

Lecture-ecriture d'un fichier binaire 

La methode openFileReadWrite ouvre un fichier en lecture et ecriture. On combine 
alors les methodes de lecture et d'ecriture. Faites attention a ne pas oublier de fermer 
le fichier en ecriture et en lecture. 

rem Codel4-01.odt bibli : Fichiers Module3 
Option Explicit 

Sub Modi f i erFi chi erBi nai re() 

Dim fl As Object, flux As Object, unPaquetO As Integer, nbOct As Long 

fl = createUnoService("com. sun. star. ucb.SimpleFileAccess") 

flux = fl.openFileReadWrite(convertToURL(nomFichl)) 

nbOct = fl ux. readBytes (unPaquetO , 3) 

Redim unPaquet(4) As Integer 

unPaquet(O) = extSigne(33) 

unPaquet(l) = extSigne(58) 

unPaquet(2) = extSigne(128) 

unPaquet(3) = extSigne(230) 

unPaquet(4) = extSigne(lOO) 

fl ux.writeBytes (unPaquetO) 

f 1 ux . fl ush 

flux.closeOutput 

flux. closelnput 

End Sub 

Ecrire un fichier texte encode 

Nous considerons ici un texte ordinaire, sans aucune marque de formatage, dont les 
caracteres sont encodes (par exemple en Windows- 1252). Pour cela il faut utiliser la 
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collaboration de deux flux issus des services SimpleFileAccess et TextOutputStream. 
et preciser le jeu de caracteres servant a l'encodage. 

Cet exemple cree un fichier de trois lignes. Adaptez a votre configuration le chemin du 
fichier indique par la constante nomFi ch2, nous l'utiliserons aussi pour lire le fichier. 

rem Codel4-01.odt bibli : Fichiers Module4 
Option Explicit 

Public Const nomFi ch2 = "C:\Docs OpenOffice\monTexte.txt" 
Sub Ecri reTexteEncode() 

Dim monTexte As Object, f2 As Object, flux As Object, URLfich As String 
URLfich = convertToURL(nomFich2) 

monTexte = createUnoServi ce ("com. sun. star . io. TextOutputStream") 

f2 = createUnoServi ce("com . sun. star. ucb.SimpleFileAccess") 
On Error Goto fichierKOl 

if f2.exists(URLfich) then f2 . kill (URLfi ch) 
flux = f 2. openFileWrite (URLfich) 
monTexte . OutputStream = flux 
monTexte. Encoding = "i so-8859-15" 

monTexte .writeString("A Laetitia, tous nos vceux " & chr(10)) 
monTexte. writeString("Ca, tu reves de theatre, ttdipe!" & chr(10)) 
monTexte. writeString("/f a A a A e i I60riuUy&€"& chr(10)) 
f 1 ux . cl oseOutput 
monTexte . cl oseOutput 
On Error Goto 0 
Exit Sub 

FichierKOl: 

Resume FichierK03 
FichierK03: 

On Error Resume Next 

fl ux . cl oseOutput 

monTexte . cl oseOutput 

On Error Goto 0 

MsgBox("Erreur d'ecriture !", 16) 
End Sub 

Pour varier un peu, nous utilisons ici le service SimpleFileAccess pour tester l'exis- 
tence d'un fichier de meme nom et le supprimer. Le principe est tres similaire a la 
gestion de fichiers Basic, mais il s'agit de methodes de l'API et nous devons 
employer obligatoirement une adresse URL. 

La methode openFileWrite ouvre un flux binaire. Le service TextOutputStream 
nous donne un deuxieme flux, monTexte, qui se charge du traitement des caracteres 
et transmet le flux resultant sur le premier flux, indique par OutputStream. 
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Rappel 

Nous avons developpe un traitement d'erreur. Vous remarquerez qu'il s'assure de fermer les deux flux qui 
ont ete ouverts. 

Si vous ne remplissez pas la propriete Encoding, le texte est encode en utf-8. Mais 
vous pouvez preciser le nom d'un encodage particulier. Le tableau 14-3 liste les noms 
pour quelques encodages courants. II existe en general plusieurs noms possibles pour 
un encodage donne, et l'API est indifferent a la casse de ces noms. 



Tableau 14-3 Noms d'encodage pour les principaux jeux de caracteres 



Jeu de caracteres 


Valeur 


Europe occidentale (ASCII/US) 


us-ascii 


Europe occidentale (DOS/OS2-437/US) 


ibm437 


Europe occidentale (DOS/OS2-850/lnternational) 


ibm850 


Europe occidentale (DOS/OS2-863/Francais canadien) 


ibm863 


Europe occidentale (Windows-1252/WinLatin1) 


wi ndows-1252 


Europe occidentale (Apple Macintosh) 


maci ntosh 


Europe occidentale (ISO-8859-1) 


iso-8859-1 


Latin 3 (ISO-8859-3) 


iso-8859-3 


Europe occidentale (ISO-8859-1 4) 


iso-8859-14 


Europe occidentale (ISO-8859-1 5/EURO) 


iso-8859-15 


Unicode (16 bits) 


non disponible 


Unicode (UTF-8) 


utf-8 



Lecriture d'un texte ignore en fait la structure de ligne : la methode wn'teStn'ng 
n'ecrit rien d'autre que la chaine de caracteres qui lui est transmise. C'est a vous 
d'ajouter le ou les caracteres de fin de ligne (caracteres CR, ou LF, ou CR+LF). 



Lire un fichier texte encode 

La lecture necessitera elle aussi la collaboration de deux flux, d'une part 
SimpleF-MeAccess et d'autre part TextlnputStream. Grace a sa propriete 
InputStream, ce dernier recoit le flux binaire pour l'interpreter comme des caracteres. 
Nous vous laisserons realiser le traitement d'erreurs. 

rem Codel4-01 . odt bibli : Fichiers Module5 
Option Explicit 
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Sub Li reTexteEncodeO 

Dim monTexte As Object, f2 As Object, flux As Object 
Dim uneLigne As String, URLfich As String 

URLfich = convertTollRL(nomFich2) 

f2 = createUnoServi ce("com . sun. star. ucb.SimpleFileAccess") 
flux = f2.openFileRead(URLfich) 

monTexte = createUnoServi ce( "com. sun. star . io.TextlnputStream") 
monTexte . InputStream = flux 
monTexte. Encoding = "i so-8859-15" 
Do while not monTexte . isEOF 

uneLigne = monTexte. read Line 

MsgBox(uneLi gne) 
Loop 

flux.closelnput 
monTexte . cl oselnput 

End Sub 

Ici aussi, nous pouvons preciser l'encodage du fichier, par defaut l'API supposera un 
encodage utf-8. La methode isEOF renvoie True quand il n'y a plus rien a lire. La 
methode read Line renvoie une ligne de texte en reconnaissant automatiquement la fin 
de ligne (caractere CR ou LF ou CR et LF) ; le texte recupere ne comporte pas la fin de ligne. 

II existe une methode readString qui recupere le texte jusqu'a trouver un des carac- 
teres de fin de ligne precises dans un tableau de Stri ng fourni en argument (reportez- 
vous a la documentation API de l'interface XTextlnputStream pour plus de detail). 

Les deux flux doivent etre fermes en fin de lecture. 



Creation et decompression d'un fichier Zip 

Le service Package de l'API est capable de lire ou d'ecrire un fichier Zip. Quelques 
informations assez generates sont disponibles dans la documentation de l'API, a 
partir de la page com . sun . star . packages. 

Le Zip telechargeable contient diverses macros pouvant servir d'outils de manipula- 
tion de Zip. Nous ne les decrirons pas dans le detail, nous contentant de montrer leur 
utilisation. 

rem Codel4-01.odt bibli : Zipper Module Exemples 
Option Explicit 

Private Const nomZip = "C:\Docs OpenOffice\monZipe.zip" 
Private Const Fichierl = "C:\Docs OpenOffice\EditerWiki.pdf" 
Private Const Fichier2 = "C:\Docs OpenOffice\baratin.txt" 
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Sub EcrireZipO 

Dim URLzip As String 

URLzip = convertToURL(nomZi p) 

' creer un nouveau ZIP avec un fichier dedans 

zipFile(URLzip, convertToURL(Fichierl) , "") 

1 ajouter un fichier dans le repertoire textes/ de ce ZIP 

zipFile(URLzip, convertToURL(Fichier2) , "textes/") 

MsgBox("Modifiez maintenant le fichier" & chr(13) & Fichier2) 

' mettre a jour le Zip 

zipFile (URLzip, convertToURL(Fi chi er2) , "textes/") 
End Sub 

Sub supprimerZipO 

Dim URLzip As String 

URLzip = convertToURL(nomZi p) 

removeFileinZip(URLzip, "baratin.txt", "textes/") 
End Sub 

Sub 1 i sterContenuZi p() 
Dim URLzip As String, nomRep As String 
URLzip = convertToURL(nomZi p) 
listZipContents (URLzip, "") 

nomRep = InputBox("Repertoi re du zip ? (xxx/)" 
listZipContents(URLzip, nomRep) 
End Sub 

Sub dezipperFichier() 
Dim URLzip As String 

Const Fichier3 = "C:\Docs OpenOffice\Tatata.txt" 
URLzip = convertToURL(nomZi p) 

UnzipAFile(URLzi p, "textes/barati n . txt" , con vertToURL( Fichier 3)) 
End Sub 

Sub zi pperArborescence() 

Dim leZip As String, arbreAzipper As String 
leZip = convertToURL("D : \essai 1 . zi p") 
arbreAzipper = convertToURL("C:\Docs OpenOffi ce\") 
zipTree(lezip, arbreAzipper) 
End Sub 

Sub dezi pperArchi ve() 

Dim leZip As String, arbreDezip As String 

leZip = convertToURL("C : \Docs OpenOffi ce\CrosWri ter . odt") 

arbreDezip = convertToURL("C:\Dezip\") 

unzipArchive(leZip, arbreDezip) 

End Sub 
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On cree un fichier Zip en donnant en arguments de la macro zi pFi 1 e : 

1 l'adresse URL du futur Zip ; 

2 l'adresse URL d'un fichier a inserer dans le Zip ; 

3 le chemin du repertoire interne au Zip dans lequel sera place le fichier : une 
chaine vide si le fichier est place a la racine ; al pha/ si le fichier est place dans le 
repertoire al pha, al pha/beta/ s'il est place dans le sous-repertoire beta, etc. 

On evitera d'utiliser des caracteres accentues ou autres non ASCII dans les noms de 
repertoire et de fichier dans un Zip. Une fois le Zip cree avec un fichier, on peut 
ajouter des fichiers, un par un, avec la meme macro. Si le fichier existe deja dans 
le Zip, il sera remplace. 

La macro removeFileinZip supprime un fichier contenu dans un Zip. Si le fichier 
n'existe pas dans le Zip une erreur est declenchee. Cette macro utilise trois 
arguments : 

1 l'adresse URL du fichier Zip ; 

2 le nom du fichier a supprimer du Zip ; 

3 le chemin du repertoire de Zip contenant le fichier a supprimer. 

La macro 1 i stZi pContents affiche les fichiers et repertoires contenus dans un reper- 
toire d'un Zip. Elle a pour arguments : 

1 l'adresse URL du fichier Zip ; 

2 le chemin d'un repertoire dans le Zip (chaine vide pour le repertoire racine). 

La macro UnzipAFile decompresse un fichier d'un Zip pour obtenir un fichier ordi- 
naire. Si le fichier n'existe pas dans le Zip une erreur est declenchee. Cette macro uti- 
lise trois arguments : 

1 l'adresse URL du fichier Zip ; 

2 l'adresse URL du fichier dans le Zip ; 

3 l'adresse URL du fichier final. 

La macro zi pTree compresse tout un repertoire, avec ses fichiers et sous-repertoires. 
Elle utilise deux arguments : 

1 l'adresse URL du fichier Zip ; 

2 l'adresse URL du repertoire a compresser (termine par un /). 

La macro unzi pArchi ve decompresse une archive Zip, avec ses fichiers et sous- 
repertoires, dans un repertoire de destination. Elle utilise deux arguments : 

1 l'adresse URL du fichier Zip ; 

2 l'adresse URL du repertoire de destination (termine par un /). 
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Lancer Implication associee a un document 

Le service SystemShell Execute est capable, par exemple, d'afficher un document 
HTML sur le navigateur configure par defaut sur le PC. Ceci necessite toutefois une 
configuration correcte d'OpenOffice.org et du systeme d'exploitation, qui doit 
retrouver l'application a partir de l'extension du fichier. Cet exemple affiche un 
fichier PDF (que vous trouverez dans le Zip telechargeable). 

rem Codel4-01 . odt bibli : Lancer Modulel 
Option Explicit 

Sub AfficherPDFO 

Dim sv As Object, fichier As String 

sv = createUnoService("com . sun . star . system . SystemShel 1 Execute") 

fichier = "C:\Docs OpenOffice\EditerWiki.pdf" 
sv.execute(fichier , "", 0) 
End Sub 

Nous invoquons le service SystemShell Execute, puis nous utilisons sa methode 
execute. Ladresse du fichier doit etre dans le format natif du systeme d'exploitation. 
La methode execute peut aussi lancer une application executable en lui fournissant 
un argument, sous forme d'une chaine de caracteres : 

sv. execute (application, argument, 0) 

Toutefois, ceci ne fonctionne pas sur tous les systemes (pour raison de securite). Le 
troisieme argument de la methode execute, s'il n'est pas nul, permet de ne pas affi- 
cher de message systeme si la methode echoue. II faut alors lui donner comme valeur 
la constante nommee : 

com . sun . star . system . SystemShel 1 ExecuteFl ags . N0_SYSTEM_ERR0R_MESSAGE 



La palette des couleurs 

La palette des couleurs est accessible par l'interface utilisateur, menu 
Outils>Options>OpenOffice.org>Couleurs. Le contenu de la palette est utilisable grace 
au service ColorTable de i'API. Cette macro affiche le nom de chacune des couleurs 
de la palette. 

rem Codel4-02 . odt bibli : Palette Modulel 
Option Explicit 
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Sub PaletteCouleursO 

dim sv As Object, lesCouleurs As Object, couleur As String 
sv = createUnoService("com. sun. star, drawing. Color-Table") 
' obteni r un tableau des couleurs de la palette 
lesCouleurs = sv.ElementNames 

for each couleur in lesCouleurs() ' lister les couleurs 

print couleur 
next 
End Sub 

Le service ColorTable nous renvoie un objet conteneur. II possede une propriete 
El ementNames, qui est un tableau, indexe a partir de zero, dont chaque element est un 
nom de couleur. Basic nous permet de balayer le tableau avec une boucle for each et 
d'afficher chaque nom de couleur. 



Attention 

Les noms des couleurs predefines sont localises. Vous n'obtiendrez pas les memes noms sur une version 
allemande d'OpenOffice.org, par exemple. 



La macro suivante montre comment recuperer la valeur d'une des couleurs de la 
palette. 

rem Codel4-02 . odt bibli : Palette Module2 
Option Explicit 

Sub lirePalette() 

dim sv As Object, c As Long, nomCouleur As String 

sv = createUnoService("com. sun. star. drawing. ColorTable") 

nomCouleur = InputBox("Donnez un nom de couleur", "", "Sun 4") 

if sv.hasByName(nomCouleur) then 

c = sv.getByName(nomCouleur) ' recuperer la valeur de couleur 
MsgBoxC'R = " & Red(c) & chr(13) & "V = " & Green(c) & _ 
chr(13) & "B = " & Blue(c), 0, nomCouleur) 

el se 

MsgBox(nomCouleur & " n'existe pas !", 16) 
end if 
End Sub 

Le service Col orTabl e nous expose la fonction hasByName. Elle renvoie la valeur True si 
le nom en argument existe bien dans la palette. Dans ce cas, la fonction getByName du 
service nous donne la valeur correspondante. Nous avons verifie l'existence du nom au 
prealable car, s'il n'etait pas reconnu par getByName, une erreur serait declenchee. A partir 
de la valeur de couleur, nous affichons ses composantes avec les fonctions Red, Green, 
Bl ue. Les instructions chr(13) servent a changer de ligne dans le message affiche. 
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Le service ColorTable n'est pas documente. II comporte aussi des methodes pour 
modifier la palette, mais elles ne fonctionnent pas. 



Penser a l'utilisateur 

Geler I'affichage du document 

Certaines macros peuvent prendre un temps non negligeable pour s' executer et, si 
elles modifient le contenu du document, I'affichage va evoluer en meme temps. Ce 
n'est pas agreable pour l'utilisateur et cela peut ralentir considerablement l'execution. 
II est possible de « geler » I'affichage sur l'interface utilisateur au debut du traitement, 
puis de le liberer en fin de traitement, ce qui permet sa mise a jour automatique. Ceci 
est realise par deux methodes de l'objet document. 

monDocument . 1 ockCont rol 1 ers 

' ici I'affichage utilisateur est bloque 
monDocument . unl ockControl 1 ers 

' ici I'affichage utilisateur est libere 

En consequence, si dans votre traitement vous souhaitez afficher une information a 
l'utilisateur, pensez a debloquer l'interface avant ! 

monDocument . unl ockControl 1 ers 

if MsgBox("Erreur rencontree, continuer ?", 20) = 7 then 
' reponse Non - terminer le programme 

el se 

' reponse Oui - continuer 
monDocument . 1 ockControl 1 ers 
end if 

Pour chaque lockControllers execute, il faut executer plus tard un 
unlockControllers. Vous ne pouvez pas executer unlockControllers sans avoir 
auparavant execute lockControllers. En effet, l'API maintient un compteur de blo- 
cage, et non pas un simple indicateur binaire. Vous devez done executer le meme 
nombre de ces instructions, quels que soient les chemins empruntes par le pro- 
gramme. Eventuellement, vous pouvez savoir si les controleurs sont encore bloques : 



if monDocument. hasControllersLocked then 
' encore bloque ! 
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Gels specifiques a Calc 

Dans un tableur, la modification d'une cellule peut entrainer des calculs en cascade et 
ralentir 1' execution d'une serie d'actions programmees. Voici comment l'empecher 
temporairement : 

monDocument . addActionLock 

' ici la mise a jour est inhibee 
monDocument . removeActionLock 

1 ici la mise a jour reprend 

II s'agit d'un compteur de blocages, pour revenir a l'etat normal, vous devez executer 
autant de remove que de add. Imbriquer un couple ActionLock dans un couple 
lockControl lers peut apporter un gain supplementaire. 

Si le document comporte des graphiques associes aux cellules a modifier, on peut 
eviter la mise a jour des graphiques pendant les modifications. Cette routine gele ou 
degele tous les graphiques du document : 

Sub bloquerGraphes(monDocument As Object, bloquer As Boolean) 

Dim lesFeuilles As Object, lesCraphes As Object, f As Long, gr As Long 

lesFeuilles = monDocument . Sheets 
for f = 0 to lesFeuilles. Count -1 
lesCraphes = lesFeuilles(f) .Charts 
for gr = 0 to 1 esGraphes . Count -1 
"if bloquer then 

1 esGraphes (g r) . EmbeddedOb j ect . 1 ockControl lers 
else 

1 esGraphes (gr) . EmbeddedOb j ect . unl ockControl 1 ers 

end i f 
next 
I next 
! End Sub 



Indiquer l'avancement du travail 

Nous avons vu avec les dialogues, qu'il existe un controle Barre de progression. II y a 
un autre moyen de rassurer l'utilisateur pendant un travail de duree non negligeable : 
le service Statuslndi cator permet d'afficher un texte et une barre de progression en 
bas d'une fenetre de document OpenOffice.org. 

Notre exemple simule l'avancement du travail avec une boucle temporisee. En pra- 
tique, cette boucle serait remplacee par le codage permettant de realiser le travail et 
on afficherait des messages plus utiles. 
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rem Codel4-02 . odt bibli : Progression Modulel 
Option Explicit 

Sub IndiquerProgressionO 

Dim monDocument As Object, avance As Object, i As Long 
monDocument = Thi sComponent 
monDocument . 1 ockControl 1 ers 

avance = monDocument. CurrentController.StatusIndicator 

avance. start("Attendez svp 100) 
For i = 1 To 100 
avance. Value = i 

if i = 75 then avance. Text = "Patience, bientot fini ..." 
Wait 80 ' ceci simule un codage prenant un certain temps 
Next 

avance. Text = "Termine !" 
wait 800 
avance .end 

monDocument . unl ockControl 1 ers 
End Sub 

Nous commencons par geler l'affichage sur l'interface utilisateur. Nous verrons en 
effet que cela n'empeche pas l'affichage de l'indicateur de progression. Puis, nous 
recuperons dans la variable avance l'objet Statuslndi cator qui appartient au contro- 
leur courant, c'est-a-dire celui de la fenetre du document ou s' execute la macro. La 
methode start de l'objet avance sert a afficher la barre de progression accompagnee 
de son texte. Le deuxieme argument est la valeur maximale de la progression. La 
barre de progression apparait au bas de la fenetre du document. 

La valeur de progression est mise a jour avec la propriete Val ue de l'objet avance. Le 
texte associe peut etre modifie par la propriete Text de cet objet. On pourra ainsi 
indiquer quelle phase du travail est en cours de realisation. 

En fin de travail, la barre de progression est supprimee en appelant la methode end 
de l'objet avance. Aussitot, le contenu habituel du bas de la fenetre reapparait. L'affi- 
chage est ensuite debloque pour l'utilisateur. 



Empecher les actions de l'utilisateur 

Si l'affichage est gele, rien n'empeche pour autant l'utilisateur de pianoter sur le cla- 
vier et done de modifier le document, bien que le resultat ne soit pas visible. Bien sur, 
il est souhaitable de prevenir l'utilisateur quand un travail va prendre un certain 
temps, avec un message prealable et un indicateur de progression, mais il vaut mieux 
se mettre a l'abri des actions intempestives. 
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La maniere la plus simple est de desactiver la fenetre du document : 
Dim fenetre as Object 

fenetre = monDocument . Cur rentControl 1 er . Frame .ContainerWindow 

fenetre. Enable = False 

' ici un codage prenant un certain temps 

fenetre. Enable = True 

Le codage execute comportera en general, comme nous l'avons vu, un gel de l'affi- 
chage et un indicateur d'avancement du travail. 

Pour traiter tous les cas, on doit desactiver toutes les fenetres du document. La sec- 
tion suivante explique comment les obtenir. 

Si un dialogue est en cours, la methode precedente ne le gele pas. On utilise alors la 
propriete Enabl e du dialogue. Meme la case X de fermeture de la fenetre de dialogue 
est inhibee. 

dig. Enable = False 

' ici un codage prenant un certain temps 
dig. Enable = True 

Les fenetres dans OpenOffice.org 

Le terme fenetre recouvre plusieurs entites logicielles : Frame, qui contient aussi les 
objets Contai nerWi ndow et ComponentWi ndow. Contai nerWi ndow represente la zone de 
fenetre geree par OpenOffice. La fenetre visible comporte en plus une marge geree 
par le systeme d'exploitation, notamment le titre de la fenetre. Lobjet 
ComponentWi ndow n'a pas d'utilite pour nous. 

Lutilisateur peut ouvrir plusieurs documents OpenOffice.org a la fois, et meme plu- 
sieurs fenetres par document. La fenetre Frame active dans OpenOffice.org est 
obtenue par : 

fenetreActi ve = StarDesktop.CurrentFrame 

Pour un document donne, la fenetre Frame principale est obtenue par : 
fenetreActi ve = monDocument. CurrentController. Frame 
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Changer la position ou taille de la fenetre 

Vous pouvez connaitre et changer la taille de la fenetre sur l'ecran, ou sa position, qui 
sont evaluees en pixels. Cet exemple pourrait etre transpose facilement a un formu- 
laire de base de donnees qu'on vient d'ouvrir : 



rem Codel4-02 . odt 
Option Explicit 



bibli : Fenetre Modulel 



Sub Posi tionTail leFenetreDocumentO 

Dim cw As Object, ps As Object, cr As String 

cw = ThisComponent.CurrentController. Frame. Contai nerWi ndow 
ps = cw.PosSize 

cr = chr(13) 

MsgBox("X = " & ps.X & cr & "Y = " & ps.Y & cr & _ 

"Largeur = " & ps. Width & cr & "hauteur = " & ps. Height, _ 
0, "Position et taille en pixels") 

' changer seulement la hauteur 

cw.setPosSize(0, 0, 0, 500, com . sun . star . awt . PosSi ze . HEIGHT) 
End Sub 

Les caracteristiques de la fenetre courante du document sont regroupees dans la pro- 
priete PosSize de la fenetre principale (Contai nerWi ndow) de l'objet fenetre (Frame) 
expose par le controleur actuellement utilise par le document. La methode 
setPosSize sert a modifier une ou plusieurs des coordonnees de cette fenetre. Le 
nombre d'arguments est toujours le meme, dans l'ordre : coordonnee horizontale X, 
coordonnee verticale Y, largeur, hauteur, et une constante nommee (tableau 14-4) 
qui precise quels elements sont a modifier. Signalons que ces coordonnees et dimen- 
sions sont legerement differentes de celles de la fenetre visible. 

Tableau 14-4 Constantes de modification de position et taille 



X 


Modifier la coordonnee X. 


Y 


Modifier la coordonnee Y. 


WIDTH 


Modifier la largeur. 


HEIGHT 


Modifier la hauteur. 


POS 


Modifier les coordonnees X et Y. 


SIZE 


Modifier la largeur et la hauteur. 


POSSIZE 


Modifier tout. 
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Document affiche avec plusieurs fenetres 

Par le menu Fenetre, l'utilisateur peut afficher plusieurs fenetres du meme document. 
Chaque fenetre est geree par un controleur. La propriete Controllers du document 
nous permet d'enumerer chacun d'eux, et ainsi d'acceder a chaque fenetre : 

rem Codel4-02 . odt bibli : Fenetre Module2 
Option Explicit 

Sub EnumererFenetres () 

Dim monDocument As Object, 1 esControl eurs As Object 

Dim unControleur As Object, ps As Object, n As Long, m As String 

monDocument = Thi sComponent 

1 esControl eurs = monDocument. Controllers 

Do While 1 esControl eurs . hasMoreElements 

unControleur = 1 esControl eurs . nextElement 

ps = unControleur . Frame. ContainerWindow. PosSi ze 

n = n+1 

m = "Fenetre " & n 

if unControleur . Frame. isActivethen m = m & " (active)" 
MsgBox("X = " & ps.X & " Y = " & ps.Y, 0, m) 

I Loop 
End Sub 

La methode i sActi ve d'une fenetre renvoie True si elle est en premier plan des fene- 
tres OpenOffice.org. 

Ordre des fenetres OpenOffice.org 

Lorsque vous manipulez plusieurs documents, une seule fenetre OpenOffice.org sera 
au premier plan. Un document est affiche dans une fenetre d'ecran, que nous obte- 
nons ainsi : 

Dim docl As Object, fenetrel As Object 

fenetrel = docl. CurrentController. Frame. ContainerWindow 

II en est de meme pour chaque document ; la methode toFront de la fenetre la fait 
passer a l'avant-plan par rapport aux autres fenetres OpenOffice.org. 

fenetrel. toFront 

La methode toBack renvoie la fenetre au plus has de la pile des fenetres : 
fenetrel. toBack 
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Fenetre visible ou invisible 

La propriete Vi si bl e de la fenetre permet de la cacher a volonte : 

fenetrel. Visible = False 

' modification invisible du document ... 

fenetrel. Visible = True 

A partir de la version 2.2 d'OpenOffice.org, un document charge de maniere invi- 
sible peut etre rendu visible de cette maniere. 

Afficher ou masquer une barre d'outils 

Chaque barre d'outils possede un nom interne. Depuis la fenetre Frame d'un docu- 
ment, il est assez facile de gerer la visibilite d'une barre d'outils : 

rem Codel4-02 . odt bibli : Fenetre Module3 
Option Explicit 

Sub bascul erBarre() 

Dim monDocument As Object, f As Object, v As Boolean, nomBarre As String 

monDocument = Thi sComponent 

f = monDocument. CurrentController. Frame 

nomBarre = InputBox("Nom interne", "Barre d'outils", "drawbar") 
v = barreVisible(nomBarre, f) 

MsgBox("Actuellement visible ? " & v, 0, "Barre " & nomBarre) 
barreVisible(nomBarre, f, not v) ' changer la visibilite 
End Sub 

' lit ou change la visibilite d'une barre d'outil 
Function barreVisible(nomBarre As String, fenetre As Object, _ 

Optional afficher As Boolean) As Boolean 
Dim conf As Object, nomRessource As String 

nomRessource = "private: resource/toolbar/" & nomBarre 
conf = fenetre. LayoutManager 

if not IsMissing(afficher) then 
if afficher then 

if IsNull (conf . getEl ement(nomRessource)) then 

conf .createElement(nomRessource) ' creer la barre 
end if 

conf . showEl ement (nomRessou rce) 
el se 

conf . hideEl ement (nomRessou rce) 
end if 
end if 

barreVisible = conf .isElementVisible(nomRessource) 
End Function 
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Depuis le document, lancez la macro basculerBarre. Essayez d'abord la valeur par 
defaut drawbar, puis essayez la barre symbol shapes. Respectez la casse pour le nom. 

La fonction utilitaire barreVisible a deux modes d'exploitation : avec seulement deux 
arguments, elle renvoie l'etat de visibilite de la barre d'outils ; avec le troisieme, elle rend 
visible ou cache la barre d'outils et renvoie l'etat final. Cette fonction utilise quelques 
methodes de l'objet LayoutManager attache a la fenetre du document. Le LayoutManager 
est charge de la gestion de tous les elements visibles, dont les barres d'outils. 

Comment trouver le nom interne d'une barre d'outils ? Dans le repertoire d'installation 
d'OpenOffice.org, sous-repertoire share/config/soffice.cfg/modules se trouvent 
une serie de repertoires ou on reconnait les noms des applications OpenOffice (par 
exemple scale pour Calc). Chacun comporte un sous-repertoire toolbar. Chaque 
nom de fichier xml de ce repertoire est un nom interne de barre d'outils. 



Une fonction Format plus puissante 

Le service de formatage des documents Writer et Calc (mais pas Draw ni Impress) 
peuvent etre utilises pour creer une fonction similaire a la fonction Basic Format, 
mais ayant plus de possibilites pour formater les nombres. La macro 
exemplesFormatAPI donne plusieurs cas d'affichage qui ne peuvent pas etre realises 
avec la fonction Basic. A la place, nous utilisons la fonction utilitaire FormatAPI 
definie apres la macro principale. 

rem Codel4-03 . odt bibli : FormatageAPI Modulel 
Option Explicit 

Sub exemplesFormatAPI () 

Dim d As Variant, s As String, f As String 

f = "+# ##0,0" ' en fr-FR le separateur decimal est la virgule 
d = 12345.67 

s = FormatAPI (d, f) ' envi ronnement linguistique de 1 ' i nstal 1 ati on OOo 
MsgBox(d & " donne : " & s , 0, "Nombre fr-FR") 

' nombre au format Suisse (il faut preciser la langue et le pays) 
f = "#'##0.00" 
d = 12345.67 

s = FormatAPI (d, f, "fr", "CH") 

MsgBox(d & " donne : " & s, 0, "Nombre Suisse") 

d =23.65 

f = "# ?/?" 

s = FormatAPI (d,f) 
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MsgBox(d & " donne : 

' format conditionnel 
f = "[<-2]""Glagla !" 

d = 35 

MsgBox(d & " donne 
d = 19 

MsgBox(d & " donne 
d = -11 

MsgBox(d & " donne 



' & s, 0, "Nombre f racti onnai re") 

(attention aux guillemets) 
';[>30]""Canicule !"";0,0"" °C""" 

' & FormatAPI(d,f) , 0, "Temperature") 

' & FormatAPI(d,f) , 0, "Temperature") 

' & FormatAPI(d,f) , 0, "Temperature") 



' exemples de formats de dates 
d = Now 

s = FormatAPI(d, "NNN 33 MMMM AAAA") 
s = s & chr(10) & FormatAPI(d, "QQ"", semaine ""WW") 
s = s & chr(10) & FormatAPI(d, "hh\h mm\mn ss\s\ec") 
MsgBox(s, 0, "Actuell ement , cal. europeen") 

' date actuell e au calendrier hebraique 

s = FormatAPI(d, " [~jewish]DD/MM/YYYY" , "iw") 

MsgBox(Date & " donne : " & s, 0, "Actuell ement , cal . hebraique") 

' date actuell e au calendrier musulman (arabe) 

s = FormatAPI(d, " [~hi jri]DD/MM/YYYY" , "ar", "TN") 

MsgBox(Date & " donne : " & s, 0, "Actuell ement , cal. musulman") 

' date actuelle au calendrier bouddiste (thai) 

s = FormatAPI(d, " [~buddhist]DD/MM/YYYY" , "th") 

MsgBox(Date & " donne : " & s, 0, "Actuell ement , cal. bouddhiste") 
End Sub 



Function FormatAPI(ByVal v As Double, fmt As String, _ 

Optional lang As String, Optional pays As String) As String 
Dim sv As Object, idiome As New com. sun . star . 1 ang . Local e 

sv = CreateUnoService("com. sun. star .util . NumberFormatter") 
sv . attachNumber Format sSuppl ier (thi sComponent) 
if not IsMissing(lang) then 
idiome. Language = lang 

if not IsMi ssi ng(pays) then idiome. Country = pays 
end if 

FormatAPI = "Chaine de format incorrecte !" & chr(10) & fmt 
On Error Resume Next 

FormatAPI = sv.convertNumberToPreviewString(fmt, v, idiome, False) 
On Error CoTo 0 
End Function 

La fo notion FormatAPI utilise deux arguments obligatoires : la valeur v a formater et 
la chaine decrivant le format. L'argument langue est optionnel, eventuellement 
accompagne de l'indication de pays, par exemple le francais de Suisse. La fonction 
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utilise le service NumberFormatter, qui a besoin d'un gestionnaire de formats numeri- 
ques (NumberFormatsSupplier) qu'on obtient du document courant, Writer ou Calc. 
Pour preciser le contexte linguistique, la methode convertNumberToPreviewString 
utilise une structure Local e, decrite au chapitre 7. Un traitement d'erreur permet de 
renvoyer un texte approprie si la methode declenche une erreur pour cause de format 
incomprehensible. 

L'interet du formatage API est que les chaines de format sont exactement celles qu'on 
peut utiliser via l'interface utilisateur de Calc pour formater une cellule contenant un 
nombre. On peut done tester sur Calc un format avant de le recopier dans la macro. 

Description 

Les differents formats possibles sont decrits dans ['aide F1 pour Calc. Recherchez dans I'index 
« Descriptions de formats ». 



Differences avec la fonction Basic Format 

Dans les chaines de format, le separateur decimal et le separateur de milliers doivent 
correspondre au Locale utilise, contrairement a l'instruction Basic Format. Lorsque 
nous havons pas impose le Locale, les exemples supposent qu'il est FR-fr. Comme 
pour Format, on doit eviter Interpretation de certains caracteres en ajoutant un \ 
devant la lettre a ignorer, et encadrer un texte par des guillemets doubles. Dans les 
formats de date, l'indication de jour et d'annee n'utilise pas, en environnement fran- 
cais, le meme caractere qu'avec la fonction Format. 



Fermer completement OpenOffice 

Lorsqu'on pilote OpenOffice depuis un programme exterieur (par exemple depuis 
VB avec COM) il est possible de fermer OpenOffice apres 1' execution du travail. Le 
codage exemple fourni ici est en OOoBasic a des fins de simplification, mais il n'est 
pas applicable facilement avec une macro OOoBasic. En effet, vous ne pouvez pas 
fermer OpenOffice depuis une macro de document, car vous sciez la branche sur 
laquelle vous etes assis : vous devez lancer une macro situee dans Mes macros ou 
Macros OpenOffice.org, et depuis OpenOffice, ce qui n'est pas pratique. 

Deux problemes sont a resoudre : 

• En tant qu'intervenant exterieur, vous ne devez pas fermer OpenOffice si l'utili- 
sateur s'en sert ! 

• Si la configuration utilise l'option de demarrage rapide, OpenOffice restera 
ouvert meme en l'absence de document en cours. 
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Apres avoir ferme vos documents de travail, executez dans votre langage l'equivalent 
de ces instructions : 

Dim coll Docs As Object 

coll Docs = StarDesktop . Components . createEnumerati on 

if not col 1 Docs . hasMoreEl ements then ' pas d'autre utilisation en cours 
StarDesktop. SuspendQuickstartVeto = True ' inhiber demarrage rapide 
oDesktop. terminate ' fermer OpenOffice 

end if 

La fermeture ne s'effectue que s'il n'existe plus aucun composant OpenOffice en 
cours. La propriete SuspendQuickstartVeto inhibe le demarrage rapide pour cet 
arret, sans changer l'option. 



Utiliser le Dispatcher 

Le Dispatcher est le mecanisme dont se sert OpenOffice.org pour executer les com- 
mandes realisees par l'interface utilisateur, par exemple depuis une entree de menu. II 
est utilise aussi par l'Enregistreur de macros. Les fonctions lancees ne font pas partie de 
l'API OpenOffice.org. La plupart sont equivalentes a des fonctions de l'API, mais sous 
un autre format d'appel, et en general necessitent que le document soit visible. Cer- 
taines possibilites sont seulement accessible par le Dispatcher, et pas par l'API. 

Les noms de commande utilises par les menus et les boutons de barres d'outils peu- 
vent etre trouves assez facilement. Dans le repertoire d'installation d'Open- 
Office.org, sous-repertoire Basis/share/config/soffice.cfg/modules se trouvent 
une serie de repertoires ou on reconnait les noms des applications OpenOffice (par 
exemple scale pour Calc). Chacun comporte un sous-repertoire menu bar et un sous- 
repertoire toolbar. Dans un editeur de texte, affichez le contenu d'un des fichiers 
*bar.xml : les commandes de Dispatcher sont facilement reperables avec leur 
prefixe .uno: et leur signification est en general evidente. Toutes ces commandes 
sont lancees sans argument. On retrouve la meme organisation dans le dossier utili- 
sateur user/config/soffice.cfg/modules, pour les menus et barres d'outils que 
l'utilisateur a configures. 

La documentation disponible sur les commandes du Dispatcher se limite a un 
tableau sur le wild d'OpenOffice.org : 

http://wiki.services.openoffice.org/wiki/Framework/Article/0pen0ffice.org_2.x_Commands 

La colonne de gauche du tableau correspond aux noms des commandes (sans le 
prefixe .uno:). Ce tableau n'indique pas si la commande necessite des arguments 
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specifiques. Le tableau 14-5 reproduit quelques commandes qui n'utilisent pas 
d'argument ou peuvent fonctionner sans argument explicite. 



Tableau 14-5 Commandes de Dispatcher 



Norn (sans le prefixe) Equivalent interface utilisateur 


Ful 1 Screen 


Affichage>Plein ecran (et revenir en affichage fenetre) 


Copy 


Edition>Copier 


Cut 


Edition>Couper 


Paste 


Edition>Coller 


Undo 


Edition>Annuler 


Redo 


Edition>Restaurer 


Reload 


Fichier>Recharger (voir la section « Recharger le document » du 
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face utilisateur) 


UpdateAll 


Outils>Actualiser>Tout actualiser 


EditDoc 


Bouton Editer le fichier (bascule mode lecture seule/ecriture autorisee) 


Pri nterSetup 


Fichier>Parametrage de 1'imprimante (ouvre le dialogue) 


Dpi ntDrai/i ami 
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rlLillcl >Mptrr^U 


txpo rx i o 
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FontDialog 


Format>Caracteres (ouvre le dialogue) 


Navigator 


Affichage>Navigateur 


Hel plndex 


Aide en ligne, onglet Index 


NewWi ndow 


Fenetre>Nouvelle fenetre 


CloseWi n 


Fermer la fenetre en cours (equivalent d'actionner la case X du coin de 
la fenetre) 


Opti onsTreeDi al og 


Outils>Options 


Basi cIDEAppear 


Affiche I'EDI 


SetlnputMode 


Dans Calc, met la cellule courante en mode Edition 



Rappelons qu'un bouton pose sur un document peut appeler une commande de Dis- 
patcher sans argument, en utilisant ses proprietes Action et URL (voir le chapitre 13, 
section « Le bouton »). 
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La routine utilitaire Di spatchSi mpl e permet d'executer facilement les commandes de 
Dispatcher qui ne necessitent pas d'argument. 

rem Codel4-02 . odt bibli : Dispatch Modulel 
Option Explicit 

Sub Di spatchSi mpl e(Commande As String, Optional fenetre As Variant) 
Dim disp as object, noArgsO 

if IsMi ssi ng(fenetre) then 

fenetre = StarDesktop.CurrentFrame 
end if 

disp = createUnoService("com. sun. star. frame. DispatchHelper") 

On Error GoTo dispErrl 

disp.executeDispatch(fenetre, ".uno:" & Commande, "", 0, noArgs) 
Sui te : 

On Error GoTo 0 
Exit Sub 

dispErrl: 

MsgBox("Commande inconnue : " & Commande, 16) 
Resume Suite 
End Sub 

Cette fonction comporte deux arguments : 

• le nom de la commande, par exemple "Pri ntPrevi ew" ; 

• eventuellement, la fenetre (Frame) d'un document OpenOffice.org a utiliser (voir 
la section precedents « La fenetre du document »). 

Void, en guise d'exemple, comment appeler le panneau de parametrage de 
l'imprimante : 

Di spatchSi mpl e(" Pri nterSetup") 



Copier-coller 

Le copier-coller est parfois la seule solution pour recopier des elements complexes 
sur un document, ou d'un document a l'autre. Lexemple suivant remplit la feuille 1 
d'un document Calc et recopie la zone dans la feuille 2 d'un autre document, a un 
autre endroit. Les deux documents doivent etre affiches (pas de mode invisible). 

rem Codel4-02 . odt bibli : Dispatch Module2 
Option Explicit 
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Sub CopierCollerEntreDocumentsO 

Dim docl As Object, doc2 As Object, props() 

Dim zonel As Object, zone2 As Object 

docl = StarDesktop. loadComponentFromURL("private: factory/seal c" , 

"_blank", 0, propsO) 
zonel = docl. Sheets(O) . getCell RangeByName("B3") 
zonel. CharHeight = 16 
zonel. String = "Bonjour" 

zonel = docl.Sheets(O) . getCell RangeByName("B2 : C5") 
zonel. CellBackColor = RCB(100 , 200 , 100) 
docl . Cur rentControl 1 er . sel ect (zonel) 

doc2 = StarDesktop. loadComponentFromURL("private:factory/scalc" , _ 

"_blank", 0, propsO) 
zone2 = doc2 . Sheets(l) . getCell RangeByName("F10") 
doc2 . Cur rentControl 1 er . sel ect (zone2) 

Di spatchSi mpl e ("Copy" , docl . Cur rentControl 1 er . Frame) 
Di spatchSi mpl e ("Paste" , doc2 . Cur rentControl 1 er . Frame) 

End Sub 

Avant de lancer la commande Copy, nous selectionnons dans le premier document la 
zone a copier. La commande Paste effectue le collage a partir de la zone selectionnee 
sur le deuxieme document. On voit dans cet exemple l'utilite de preciser la fenetre 
sur laquelle la commande va s'appliquer. 

Lancer une macro d'un autre document 

La situation a resoudre est la suivante : depuis une macro lancee depuis un document 
ou depuis Mes macros, comment executer une macro situee dans un autre document ? 
Dans l'exemple qui suit, il s'agit de la macro afficher situee dans la bibliotheque 
maBibli du document Afficheur.odt. On suppose que ce document a ete prealable- 
ment charge, manuellement ou par programme. Dans ce dernier cas, le document ne 
doit pas etre charge en mode invisible (option Hidden), et 1' execution de macro doit 
etre activee (option MacroExecutionMode). 

Le lancement de la macro s'effectue grace au Dispatcher, en lui passant une URL 
particuliere. 

rem Codel4-02 .odt bibli : Dispatch Module3 
Option Explicit 

Sub lancerMacroAutreDoc() 

Dim disp as object, resu As Variant, noArgsQ 
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fenetre = StarDesktop.CurrentFrame 

disp = createUnoService ("com. sun. star. frame.DispatchHel per") 
resu = ch'sp.executeDispatch (fenetre, 

"macro://Afficheur/maBibli.Modulel.afficher(Hello 00o!)", 

"", 0, noArgs) 
if resu. State = 1 then 

MsgBox("Macro executee") 
el se 

MsgBox("Echec de lancement") 
end if 
End Sub 

A 1' execution de la macro lancerMacroAutreDoc, on verra s'afficher un message 
« Hello OOo! » qui est produit par la macro af fi cher. Une fois cette fenetre de mes- 
sage fermee, le message « Macro executee » apparait : la macro appelante ne reprend 
qu'apres la fin d'execution de la macro appelee. On remarque que dans ce mode 
d'appel il est inutile de charger explicitement la bibliotheque maBi bl i , puisqu'Open- 
Office.org le fait. 

La macro afficher a interprete tout le texte comme un seul argument. Les argu- 
ments d'appel de la macro sont separes par des virgules, chaque argument etant tou- 
jours recupere par la macro comme un Stri ng. 

La methode executeDi spatch renvoie une structure Di spatchResultEvent, dont 
1' element State contient la valeur 1 si la macro appelee a pu etre executee, ou la 
valeur 0 si la macro n'a pu etre trouvee. La macro appelee ne peut pas renvoyer 
d'information a son appelant. 



Traitements specifiques a MS-Windows 

Utiliser les ressources propres au systeme d'exploitation MS-Windows apporte de 
nouvelles possibilites. En contrepartie, les codages les utilisant ne pourront s'executer 
sur les autres systemes d'exploitation supportes par OpenOffice.org. 

Acceder a la base de registres de MS-Windows 

Didier Dorange-Pattoret est l'auteur initial de cette macro, qui lit des cles de la base 
de registres utilisee par MS-Windows pour afficher la version du systeme d'exploita- 
tion de l'ordinateur. Elle utilise des fonctions situees dans la bibliotheque 
ImportWizard de soffice. 
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I Sub VersionValue 
Const H K E Y LOCA L MACH I N E = &H80000002 
Dim sVersion as String 

Gl obal scope . Basi cLi brari es . LoadLi brary ("ImportWizard") 

OpenRegKey(HKEY_LOCAL_MACHINE , 

"Software\Mi crosoft\Wi ndows\CurrentVersion\") 
sVersion = QueryValue(HKEY_LOCAL_MACHINE , 

"Software\Mi crosoft\Wi ndows\CurrentVersi on\" , "ProductName") 

If sVersion = "" Then 

OpenRegKey (HKEY_LOCAL_MACHINE , 

"SOFTWARE\Microsoft\Windows_NT\CurrentVersion\") 
sVersion = QueryVal ue(HKEY_LOCAL_MACHINE , 

"SOFTWARE\Microsoft\Windows NT\CurrentVersion\" , "ProductName") 
End If 

Print sVersion 

End Sub 

On en deduit comment acceder a d'autres cles de la base de registres (dont la struc- 
ture depend de la version de MS-Windows). 

Utiliser I'API de MS-Windows 

Certains developpements peuvent necessiter l'appel de fonctions internes de ce sys- 
teme d'exploitation. Que ce soit, comme dans la section precedente, pour acceder a la 
base de registres, pour utiliser d'autres fonctionnalites ou encore pour migrer un 
applicatif existant, Basic permet de les definir pour ensuite les appeler dans les 
macros comme des fonctions internes. 

DeclareFunction RegOpenKeyEx Lib "advapi32.dll" Alias "RegOpenKeyExA" _ 
(ByVal hKey As Long, 

ByVal IpSubKey As String, 

ByVal ul Options As Long, 

ByVal samDesired As Long, 

phkResult As Long) As Long 

DeclareFunction FindWindow Lib "user32" Alias "FindWindowA" _ 
(ByVal IpClassName As long, _ 

ByVal lpWindowName As String) As Long 

DeclareFunction SendMessage Lib "user32" Alias "SendMessageA" _ 
(ByVal hwnd As Long, _ 

ByVal wMsg As Long, _ 

ByVal wParam As Long, _ 

ByVal lParam As long) As Long 
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L'instruction Declare est tout-a-fait analogue a celle utilisee lors des appels d'API 
Win32 depuis d'autres langages comme Visual Basic™. Les habitues ne devraient 
done pas etre perturbes. Vous trouverez un exemple d'utilisation de ces fonctions 
dans la macro InstallVi rgule disponible sur le site fr.openoffice.org. Cependant, 
l'operateur AddressOf n'existant pas, vous ne pourrez pas utiliser d'instructions 
Cal 1 back necessaires par exemple a l'implementation de Hooks. 

Cette technique permet egalement d'appeler toute fonction dans une DLL que vous 
auriez creee dans un autre langage. Ajoutons quelques remarques d'utilisation : 

• Lutilisation de Cal 1 pour appeler une routine de DLL n'est obligatoire que si la 
routine n'a pas d'argument et ne renvoie pas de resultat. Lutilisation de Cal 1 est 
interdite si la routine renvoie un resultat. 

• La DLL peut etre situee dans un repertoire quelconque, il suffit d'indiquer le che- 
min complet en syntaxe MS-Windows. Le chemin peut comporter des espaces 
ou des caracteres accentues. 

• II faut respecter la casse pour le nom de la fonction dans la DLL, par contre la 
casse est indifferente pour le nom employe dans le codage. 

• Dans la declaration, tout argument passe par valeur doit etre declare avec ByVal . 

• On ne doit pas utiliser ByVal pour recuperer un argument de type String. De 
plus, il faut reserver la taille memoire en initialisant la variable chaine de caracte- 
res a une longueur suffisante, avec la fonction Basic Stri ng. 

• Pour passer une valeur dans un argument de type Long, il faut imperativement 
mettre cette valeur dans une variable intermediate de type Long. 



Manipuler les objets COM 

Etant dans le contexte particulier de lutilisation d'OpenOffice.org uniquement sous 
environnement MS-Windows, il peut quelquefois etre interessant d'utiliser les tech- 
nologies propres a ce systeme d'exploitation. 

Toujours depuis nos macros, nous avons la possibilite d'utiliser un pont vers la tech- 
nologic COM et utiliser les serveurs COM et activeX. 

rem Codel4-06 . odt bibli : Standard Modulel 
Option Explicit 

'Utilisation de MS Word depuis une macro OpenOffice.org 

Sub "loading MSWord( ) 

Dim oword As Object, odoc As Object 

oword = CreateObject("Word. Appl ication") 

' l'objet va utiliser 1 'API de Word 
oword. Visible = True 
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odoc = oword . Documents .Add 

odoc . Range .Text = "Hello World!" 

End Sub 



'Utilisation d'Internet Explorer depuis une macro OpenOffice.org 
Sub using IE( ) 
Dim IE As Object 

IE = CreateObject("InternetExplorer . Application. 1") 

' l'objet va utiliser 1 'API d'internet Explorer 
IE. Visible = 1 

IE . Navi gate ("http : //f r . openof f i ce . org") 
End Sub 

Le premier exemple instancie MS-Word pour y ecrire le fameux « Hello World ! ». 
Le deuxieme exemple lance Internet Explorer avec FURL d'OpenOffice.org. 

Une fois l'objet COM obtenu avec la fonction Basic CreateObject, nous pouvons 
l'utiliser dans notre macro avec sa propre API comme le montre oword . Documents . Add 
ou bien odoc . Range . Text. 

II existe une syntaxe qui rassemble la declaration de variable et l'initialisation par 
CreateObject : 

Dim oword As New Word . Appl i cati on 



Attention API differentes 

Utiliser des API differentes dans un meme programme necessite une certaine rigueur pour ne pas melan- 
ger les concepts. Les macros OpenOffice.org ont leurs propres API et philosophic les objets instancies les 
leurs. Le tout est de ne pas se melanger les pinceaux et surtout de bien documenter votre code. 



Si ces deux exemples ont un interet limite (sauf eventuellement a des fins de migra- 
tion pour l'acces a Word), la methodologie peut etre interessante sur des applicatifs 
specifiques developpes avec ces technologies, ou pour utiliser les objets du scripting 
de MS-Windows : Scri pti ng .Dictionary et Scri pti ng . Fi 1 eSystemObject. 



Piloter OpenOffice.org par COM Automation 

Une application sous MS-Windows peut piloter OpenOffice.org pour, par exemple, 
ecrire ou lire un document Writer ou Calc. Mais, contrairement a Word ou Excel, on 
ne dispose pas d'une bibliotheque de types, done pas de possibility d'autocompletion. 
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En programmant a travers COM, les noms des proprietes et des methodes de l'API ne 
sont pas sensibles a la casse. Les pseudo-proprietes sont aussi utilisables. Les tableaux 
reels, comme ElementNames fournis par certains objets, peuvent etre indexes normale- 
ment. En revanche, les pseudo-indexations de collections permises par OOoBasic doi- 
vent etre remplacees par l'usage de la methode getBylndexO de l'objet collection. 

Pour chaque langage, la difficulte est de trouver l'equivalent de quelques instructions 
OOoBasic, notamment : 

• creer un objet ayant une structure UNO ; 

• creer un tableau de PropertyVal ue, avec un index debutant a zero ; 

• creer un tableau « vide » ; 

• trouver l'equivalent de StarDesktop, CreateUnoService, ConvertToURL ; 

• trouver la valeur correspondant a une constante nommee de l'API. 

Dans la section CodeSnippets de OOoForum http://www.oooforum.org/forum/, vous 
trouverez notamment le fil de discussion Using COM for OOo with different languages 
qui presente des exemples de programmation COM avec divers langages dont VB, 
C#, Python, LotusScript, Delphi. 



Pour aller plus loin 

Le Developer's Guide decrit les particulates de I'interfacage avec COM dans sa section Professional 
UNO>UNO Language Bindings>Automation Bridge. Les details techniques signales peuvent repondre a 
certaines interrogations. 

Le SDK fournit plusieurs exemples de pilotage d'OpenOffice.org : 

• dans le sous-repertoire exampl es/CLI/ : langages VB.NET et C# ; 

• dans le sous-repertoire exampl es/OLE/ : langages Delphi et VbScript. 



Un des auteurs de ce livre a cree des boites a outils COM pour les langages de pro- 
grammation Delphi 7, VBA/VB6, VE.NET, VBScript et JScript. Ces logiciels libres 
sont telechargeables sur l'lnternet : 

• en version francaise : http://fr.openoffice.org/Documentation/How-to/ 
indexht-programmation.html (voir en bas de page la section Autres langages) ; 

• en version anglaise : VBx OOo tool : http://www.ooomacros.Org/dev.php#240562. 

Ces boites a outils sont concues pour faciliter le transcodage depuis OOoBasic. Elles 
sont baties sur le meme modele : un fichier Zip contenant une bibliotheque de rou- 
tines dont les noms sont proches de ceux employes par OOoBasic, une liste de cons- 
tantes, des exemples d'utilisation, et un manuel explicatif. Ce dernier precise en outre 
les particularites rencontrees pour chaque langage. Vous pouvez vous inspirer de ce 
travail pour creer l'equivalent dans un autre langage de programmation (et meme 
apporter votre contribution en le mettant en libre disposition). 
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Void le transcodage en VBA de la macro Bonjour du chapitre 1, en utilisant les rou- 
tines de la boite a outils (imprimees en gras dans ce codage). Aux differences syntaxi- 
ques pres, on aurait un codage identique dans les autres langages. 

Sub BonjourVBA 

Dim monDocument As Variant, monTexte As Variant, monCurseur As Variant 
ConnectOpenOf f i ce 

Set monDocument = Star-Desktop. CurrentComponent 
Set monTexte = monDocument .Text 
Set monCurseur = monTexte. createTextCursor 
monCurseur. gotoEnd False 

monTexte. insertString monCurseur, "VBA vous salue !", False 
monTexte . i nsertControlCharacter monCurseur, 
OOOtextControlCharacterPARAGRAPH BREAK, Fal se 
DisconnectOpenOffice False 
End Sub 

Le mecanisme de Listener n'est pas realisable simplement, car le pont COM d'Open- 
Office.org n'implemente pas les primitives de call-back qui seraient necessaires. Le 
Developers Guide (a la fin du chapitre Automation Bridge) propose une solution de 
remplacement : 

1 Creer une DLL ActiveX. 

2 Implementer dans cette DLL une interface UNO listener qui traitera tous les 
evenements decrits dans la documentation de l'interface du Listener. 

3 Dans le programme externe, notifier votre Listener sur l'objet UNO qui sera la 
source des evenements a traiter. 

4 Si necessaire pour votre application, vous devrez traiter vous-meme l'echange de 
donnees entre le programme externe et la DLL ActiveX. 

Loutil Xray, ecrit en OOoBasic, peut etre appele depuis un programme pilotant 
OpenOffice.org par COM, en utilisant le mecanisme du Scripting Framework. C'est 
ce que font les boites a outils avec une routine du meme nom xray. Lexemple suivant 
en JScript ouvre un nouveau document Writer et fait analyser le document par xray. 

var maDoc; 

maDoc = StarDesktop. 1 oadComponentFromURL ("private : facto ry/swri ter" , 
"_blank", 0, dummyArray); 

xray(maDoc) ; 

La boite a outils Delphi comporte en plus sa propre version de Xray, ecrite en 
Delphi. 



Techniques avancees pour le poste de travail 

Chapitre 14 



Envoyer un document par courrier electronique 

II existe deux services de l'API permettant d'envoyer un courrier electronique : 

• Simpl eCommandMai 1 utilise l'application de messagerie fonctionnant en ligne de 
commande, si une telle application existe. Ceci ne semble pas fonctionner sous 
Windows. 

• SimpleSystemMail utilise l'application de messagerie par defaut, ce qui aboutit a 
ouvrir une fenetre de votre logiciel de messagerie favori, montrant le message 
electronique pre-rempli, pret a etre envoye. 

Tous les champs courants peuvent etre remplis, a l'exception du texte du message. 
Pour transmettre une information, on utilisera a la place le contenu d'un ou plusieurs 
fichiers attaches au courrier. 

rem Codel4-02 . odt bibli : Mel Modulel 
Option Explicit 

Sub Envoye rE_Mai 1 () 

Dim sv As Object, unClient As Object, monMel As Object 

Dim enCopie(l) As String, annexes(l) As String ' (exemples) 

' sv = createUnoServi ce("com. sun . star . system. Simpl eCommandMai 1 ") 
sv = c reateUnoSe rvi ce ( " com . sun . star . system . Si mpl eSystemMai 1 " ) 
unClient = s v. querySi mpl eMail Client 
if IsNull (unClient) then 

MsgBox("Client de messagerie non disponible", 16) 

stop 
end if 

monMel = unClient. createSimpleMailMessage 

with monMel ' evite de repeter monMel. xxxx 
.Recipient = "BillCates@microsoft.com" 
enCopie(O) = "alainOici" 
enCopie(l) = "julieOailleurs" 
.CcRecipient = enCopie() 
.Originator = "inconnu@neant.fr" 
.Subject = "Ceci est un test" 

annexes(O) = convertToURL("C:\Dezip\Icones\etoile_26.bmp") 
annexes(l) = convertToURL("C:\Docs OpenOffice\baratin.txt") 
.Attachement = annexes() 
end with 

unClient. sendSimpleMailMessage(monMel , 0) 

End Sub 

Le service est d'abord invoque, puis on lui demande de chercher le client de messa- 
gerie (ce terme designe l'application qui va envoyer le courrier electronique). La 
methode createSimpleMailMessage du client nous renvoie un objet courrier vide. 
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C'est une structure dont les elements sont les champs principaux du courrier. Votre 
client de messagerie acceptera ou non que le champ Originator soit quelconque. 

L'objet courrier est envoye au client avec la methode sendSimpl eMail Message. Le 
deuxieme argument peut contenir un des indicateurs suivants, ou les deux, en les 
additionnant : 

com . sun . star . system . Si mpl eMai 1 CI i entFl ags . NO USER INTERFACE 
com . sun . star . system . Si mpl eMai 1 CI i ent FT ags . NO LOGON DIALOG 

Le premier indicateur envoie le courrier sans afficher la fenetre du client de messa- 
gerie. Le deuxieme indicateur n'affiche pas la fenetre de connexion si l'utilisateur 
n'est pas connecte ; dans ce cas, une erreur se produit. 



Utiliser un serveur web 

Comme nous l'avons vu precedemment, OpenOffice.org utilise des URL pour ouvrir 
les documents. Nous allons detourner ici cette fonctionnalite pour illustrer une utili- 
sation possible d'une macro pour interagir avec un serveur web. 

Imaginons un serveur web exposant un script PHP (ou autre) a FURL 
http://monsite.com/lescript.php. Ce script attend un argument prenom et se charge 
d'afficher un message de bienvenue dans le navigateur. LURL a utiliser sera done : 
http://monsite.com/lescript. php?prenom=Toto 

La macro suivante appelle le serveur, lui passe un prenom et y lit la reponse. 

sub AppelURLO 

dim lePrenom as string 
dim monllRL as string 
dim laReponse as string 

'On demande le Prenom 

lePrenom=InputBox("Quel est votre Prenom ?") 

'On construit 1 'URL 
monURL=ConvertToURL 

("http://monsite.com/lescript. php?prenom=" & lePrenom) 

'Ouverture de la communication 
Open monURL for input as #1 

'On recupere la reponse du serveur 
1-ineinput #1, laReponse 
close #1 
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'On affiche le resultat 

MsgBox laReponse.O, "Reponse du serveur" 

end sub 

Comme nous le voyons, FURL est reconstruite par simple concatenation de chaines de 
caracteres. La fonction ConvertToURL est utilisee pour prendre en charge d'eventuels 
caracteres speciaux dans la variable TePrenom. Comme la macro doit lire la reponse 
affichee par le serveur, nous utilisons l'instruction open ... for input surl'URL. 

Le fait d'utiliser monURL comme nom de fichier a le meme effet que de l'appeler 
depuis un navigateur : le script va etre interprets et la reponse du serveur produite. 
Ainsi, des l'ouverture du fichier, le serveur web est sollicite. 

Pour lire la reponse, il suffit d'utiliser l'instruction 1 i ne i nput comme on le ferait sur 
un veritable fichier. Lexemple utilise sous-entend qu'il n'y a qu'une seule ligne a lire. 
Une boucle peut etre utilisee si ce n'est pas le cas. 

Cet exemple simpliste permet d'ouvrir l'horizon a toute sorte d'interaction si, par 
exemple, le serveur est prevu pour agreger des donnees ou s'il est couple a une base de 
donnees. 



Intercepter un evenement : le Listener 

Nous savons qu'une macro peut etre declenchee a l'ouverture d'un document, ou a sa 
fermeture, etc. Nous avons vu dans les boites de dialogue et dans les formulaires com- 
ment certains evenements peuvent etre interceptes par une macro OOoBasic. Cette 
affectation d'une macro OOoBasic a un evenement via l'interface utilisateur n'est qu'un 
sous-ensemble de tous les evenements susceptibles d'etre analyses. Le mecanisme 
d'interception d' evenements (en anglais Listener, signifiant ecouteur) offert par l'API 
est un moyen plus general, donnant acces a un grand nombre d'evenements. 

La seule source d'information disponible sur les differents evenements est l'API. 
Pour intercepter des evenements non accessibles par les moyens ordinaires, il vous 
faudra etudier les pages de l'API concernant un objet donne et chercher les interfaces 
dont le nom se termine par Li stener. 

Par exemple, supposons qu'un objet Machin prenne en charge une interface imagi- 
naire XBlablaLi stener situee dans labranche com. sun. star. true de l'API. Lorsque 
vous lirez la page correspondante de la documentation, vous trouverez par exemple 
trois noms de fonction, correspondant chacune a un evenement particulier : 
• debute rTravai 1 ; 
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• fai reQuelqueChose ; 

• fai reAutreChose. 

Pour intercepter les evenements de Bl abl a, vous devez vous inscrire comme ecouteur. 
On utilise pour cela, d'une part la fonction Basic CreateUnoLi stener qui renvoie un 
objet specifique, d'autre part une methode de l'objet Machin, destinee a realiser la 
« mise sur ecoute ». 

Dim ecouteur As Object 
Dim Machin As Object 

' (on suppose que Machin est deja obtenu) 

ecouteur = CreateUnoLi stener("monGrainDeSel " , 

"com . sun . star . true .XB1 abl aLi stener") 
Machi n .addBlablaLi stener (ecouteur) 

Le mecanisme d'interception est maintenant en place. Pour chaque evenement con- 
cernant l'interface Blab! a de l'objet Machin, il va executer une macro. Le nom de la 
macro se compose : 

• du premier argument de CreateUnoLi stener, ici ce sera monCrainDeSel, 

• suivi du nom de 1' evenement, par exemple bl abl aDebute. 

Attention 

Le mecanisme d'interception essaye aveuglement d'executer une macro de ce nom. Si elle n'existe pas, 
vous aurez une erreur Basic qui ne vous precisera pas quel est le nom manquant. 

Cela signifie que vous devez avoir ecrit une macro pour chacun des evenements pris 
en charge, meme si vous ne vous interessez pas a certains des evenements. Dans 
notre exemple, vous devrez avoir quatre macros : 

Sub monGrai nDeSel debuterTravail () 

End Sub 

Sub monGrai nDeSel faireQuelqueChose() 
End Sub 

Sub monGrai nDeSel fai reAutreChose () 
End Sub 

Sub monGrai nDeSel _disposing() 
End Sub 
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La derniere macro concerne un evenement toujours present dans les Listener. II 
peut etre appele en dehors de toute execution de macro, en particulier quand le docu- 
ment va etre ferme. D'une maniere generale, vous devez traiter les evenements 
herites par un Li stener. 

La structure exacte de chaque macro depend de l'interface et de l'evenement. En 
general, l'evenement transmet une information que vous pouvez obtenir en premier 
argument de la macro. Certains evenements offrent a l'ecouteur la possibilite de les 
approuver ou non (droit de veto). Pour ceux-la, le sous-programme est une fonction 
renvoyant une valeur Boolean. Une valeur True accepte l'evenement, une valeur 
Fal se le supprime. 

Un gestionnaire d'evenements est supprime avec la methode removeXxxLi stener de 
l'objet ecoute : 

Machi n . removeBlablaListener(ecouteur) 

II faut placer la mise sur ecoute et la fin de la mise sur ecoute au bon moment, 
compte tenu que vous ne pouvez pas tout maitriser, par exemple un formulaire qui se 
connecte a une base de donnees et declenche ainsi des evenements des l'ouverture du 
document, ainsi qua la fermeture du document. 

Plusieurs programmes peuvent greffer un gestionnaire d'evenements sur le meme 
ensemble d'evenements. Par exemple, les evenements interceptables avec l'onglet Eve- 
nements des controles de boite de dialogue ou de formulaire sont eux-memes traites 
par un gestionnaire d'evenements interne. Lorsque vous approuvez un evenement, il 
se peut qu'un autre gestionnaire soit appele ensuite, qui donnera son veto. Un evene- 
ment a lieu seulement si aucun gestionnaire ne s'y oppose. 

Pour un premier abord des Listener, vous pouvez regarder le jeu leBOOolier.sxd 
disponible sur le site fr.openoffice.org. Un Listener sur la frappe de touche dans un 
document Draw est mis en place pour controler l'appui des fleches de direction afin 
de deplacer un objet Draw. Nous reproduisons ici ce traitement specifique. 

Sub Regi sterKeyHandl er 

oDocView = Thi sComponent . getCurrentControl 1 er 

oKeyHandler = createUnoLi stener 

("MonJeu " , "com. sun. star. awt.XKeyHandler") 

oDocVi ew . addKeyHandl er (oKeyHandl e r) 
End Sub 

i _ 

Sub UnregisterKeyHandler 

on error resume next 

oDocVi ew. removeKey Handler (oKeyHandl er) 
End Sub 
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Function MonJeu KeyPressed(oEvt) as Boolean 
select case oEvt . keyCode 

case 1026: 'Fleche Gauche 
if not isPause then 
bougePanier=-l 

call Deplacepanier(bougePanier) 
endi f 

case 1027: 'Fleche droite 
if not isPause then 
bougePani er=l 

call Deplacepanier(bougePanier) 

endi f 
case 1281: 'Esc 

arret=true 
case 527: 'Pause 

call TooglePause 
case else: 

' autres touches 
end select 

MonJeu KeyPressed=true 

End Function 
i _ 

Function MonJeu KeyRel eased (oEvt) As Boolean 

MonJeu KeyRel eased = False 
End Function 

L'utilisation d'un Listener se fait en deux etapes. II faut d'abord le preparer. C'est ce 
que fait la routine Regi sterKeyHandler en utilisant la fonction CreateUnoLi stener. 

Comme nous l'avons vu, cette fonction a besoin de deux arguments, le premier etant 
le prefixe des fonctions d'evenement qui seront appelees, le deuxieme le type du 
Li stener que nous trouverons dans le module com . sun . star . awt de l'API. 

On y trouvera des Li stener concernant le clavier, la souris, les menus, dont certains 
sont enumeres dans le tableau 14-6. 



Tableau 14-6 Exemples de Listener 



XKeyHandler 


Gere un evenement de type clavier KeyEvent - Peut bloquer I'evenement 


XKeyLi stener 


Gere un evenement de type clavier KeyEvent 


XMenuLi stener 


Gere un evenement de type menu MenuEvent 


XMouseCl i ckHandl er 


Gere un evenement de type souris MouseEvent - Peut bloquer I'evenement 


XMouseLi stener 


Gere un evenement de type souris MouseEvent 
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Chaque Li stener est associe a un type d'evenement qui est en fait une structure ega- 
lement disponible dans le module com . sun . star . awt. Nous ne nous attacherons qua 
I'evenement KeyEven. 

Le Listener est alors declare par la methode addKeyHandler sur le document. La 
routine UnregisterKeyHandler permet de retirer ce Listener avec la methode 
removeKeyHandler. 

Une fois un Listener declare, tout evenement le concernant appellera la methode 
concernee associee au prefixe. 

Ainsi, pour notre Listener de clavier, nous devons definir les fonctions 
MonJeu_KeyPressed et MonJeu_KeyRel eased. 

Chacune de ces fonctions accepte en argument d'entree un objet de type KeyEvent 
renseignant sur le contexte dans lequel I'evenement est intervenu (tableau 14-7). 



Tableau 14-7 L' evenement KeyEvent 




KeyCode 


Code numerique unique - com . sun . star . awt . Key 


KeyChar 


Caractere Unicode transmis ou 0 


KeyFunc 


Constante de fonction - com . sun . star . awt . KeyFunction 


Modi fi ers 


Etat des touches mortes (Shift, Ctrl et Alt) - 
com. sun . star . awt . KeyModi f i er 


Source 


Objet ayant engendre I'evenement 



Notre jeu ne s'interesse ici qu'au code de la touche afin de pouvoir reagir sur cer- 
taines. Ces codes numeriques peuvent facilement etre obtenus en ajoutant une ligne 
dans la macro lors de la phase de test 



print oevt. KeyCode 

Neanmoins, les touches sont pour la plupart disponibles dans le groupe de constantes 
com . sun . star . awt . Key. 

Enfin, nous constatons que ces fonctions sont de type booleen. Ceci est important 
puisqu'il s'agit en fait de traiter un Handler qui va pouvoir bloquer I'evenement en 
evitant qu'il soit transmis au document. Si la fonction retourne True, I'evenement est 
bloque et n'est pas transmis. Si la fonction retourne Fal se, I'evenement est transmis 
au document. 

Notez enfin, que meme si aucun traitement n'est envisage dans une fonction d'evene- 
ment d'un Li stener, il faut quand meme la declarer dans la macro. 
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Modifier des macros par programmation 

L'ecriture dynamique de macros 

La programmation courante (a 99 %) consiste a concevoir des sequences d'instruc- 
tions, les ecrire au clavier, les sauvegarder dans un fichier, puis executer ce fichier. 
Dans certaines situations, il est interessant de creer une serie d'instructions « a la 
volee », par programme, et de les incorporer dans 1'algorithme de ce meme pro- 
gramme. Ceci est parfaitement possible en OOoBasic, avec une petite pirouette. 

Rappel 

Nous avons deja presente dans les chapitres 2 et 4 le concept des bibliotheques et des conteneurs de 
bibliotheques. 

Un conteneur de bibliotheque, par exemple BasicLibraries, expose plusieurs 
methodes permettant de modifier son contenu : 

• hasByName("bibliX") renvoie True si la bibliotheque bibliX existe dans le conte- 
neur. 

• getByName("bi bl iX") renvoie l'objet bibliotheque correspondant. 

• removeLibrary("bib"liX") supprime la bibliotheque en argument. 

• createLibrary("bib"liX") cree la bibliotheque en argument et renvoie l'objet 
correspondant. Attention, cette bibliotheque ne contient encore aucun module. 

Les methodes specifiques des conteneurs de bibliotheques sont documentees dans la 
branche com. sun. star. script aux interfaces : 

• XLibraryContainer, 

• XLibraryContainer2, 

• XLi braryContai nerPassword. 

De maniere tees similaire a un conteneur de bibliotheques, une bibliotheque est elle- 
meme un conteneur de modules. Une bibliotheque expose un tableau ElementNames 
listant les noms de modules quelle contient. Plusieurs methodes permettent de gerer 
les modules d'une bibliotheque : 

• hasByNameC'moduleX") renvoie True si le module moduleX existe dans la biblio- 
theque. 

• getByNameC'moduleX") renvoie une chaine de caracteres qui est le texte complet 
du module. 

• removeByNameC'moduleX") supprime le module en argument dans la bibliothe- 
que. 
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• i nsertByName("modul eX" , texteModule) ajoute le module modul eX dans la 
bibliotheque, le deuxieme argument etant une chaine de caracteres contenant le 
texte complet du module. 

• replaceByNameC'moduleX" , texteModule) remplace le contenu du module 
modul eX. 

Avec ces methodes, il est assez aise de creer une bibliotheque, puis de lui ajouter un 
module ou de modifier ce dernier. Dediez une bibliotheque a votre module dyna- 
mique. Construisez dans ce module une routine Sub ou Function et appelez la rou- 
tine depuis le reste du programme (qui reste fixe). 

Un exemple plus complexe se trouve dans l'outil Xray, dont nous reparlerons a 
l'annexe A. La bibliotheque dynamique s'appelle XrayDyn. Son unique module con- 
tient plusieurs routines dont le contenu est dynamique, ce qui a conduit a systema- 
tiser la maniere de le modifier. Voyez pour cela dans la bibliotheque Xray, module 
_Uti 1 i ti es, les macros getlnfo, Insertlnfo, getModuleText, saveModul eText. Des 
exemples d'utilisation se trouvent dans le module Mod 3 de la bibliotheque Xray. 



Modifier les macros d'un autre document 

Si vous devez effectuer des modifications systematiques dans des bibliotheques de 
macros d'une serie de documents, la methode manuelle consiste a ouvrir chaque 
document, puis chaque bibliotheque, puis chaque module de bibliotheque, pour 
effectuer la modification si necessaire, sauver et fermer le document : tache particu- 
lierement ennuyeuse. 

Nous allons, avec une macro, ouvrir un document et rechercher dans chaque module 
de ses bibliotheques de macros l'apparition d'un mot. S'il est present, nous ajouterons 
un commentaire en tete du module. II suffirait d'ajouter une boucle pour modifier 
ainsi toute une serie de documents. 

rem Codel4-05 . odt bibli : Standard Modul el 
Option Explicit 

Sub Modi fMacrosO 

Dim monDocument As Object, bLib As Object, lesBiblis As Object 

Dim uneBibli As Object, lesModules As Object 

Dim adresseDoc As String, nomBibli As String 

Dim nomModule As String, codageModule As String 

Dim motRecherche As String, liste As String 

Dim x As Long, y As Long, modif As Boolean 

Dim propFich(O) As New com . sun . star . beans . PropertyVal ue 

motRecherche = "servCrad" 

propFich(O) .Name = "Hidden" 

propFich(O) .Value = True 
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adresseDoc = convertToURL("C:\Docs OpenOffi ce\Tata. sxd") 
monDocument = StarDesktop . LoadComponentFromURL(_ 
adresseDoc, "_blank", 0, propFichO) 
"if IsNul 1 (monDocument) then 

MsgBox("Le document n'existe pas", 16) 

stop 
end "if 

modif = false 

bLib = monDocument . BasicLibraries 
lesBiblis = bLib. ElementNames 
for x = 0 to UBound(lesBiblis) 
nomBibli = lesBiblis(x) 

"liste = liste & "Bi bl i otheque " & nomBibli & chr(13) 
uneBibli = bLib.getByName (nomBibli) 

' charger la bibliotheque pour voir le contenu de ses modules 
bLib . LoadLi brary (nomBi bl i ) 
lesModules = uneBi bl i . El ementNames 
for y = 0 to UBound(lesModules) 
nomModule = lesModules(y) 
liste = liste & "Module " & nomModule 
codageModule = uneBi bl i . getByName(nomModul e) 
if InStr(codageModule, motRecherche) > 0 then 

1 modification du module : ajout d'un commentaire 

codageModule = "REM modi fie " & _ 

chr(13) & chr(10) & codageModule 
uneBibli . repl aceByName(nomModul e , codageModule) 
modif = True 

liste = liste & " mot trouve" & chr(13) 
else 

liste = liste & " mot PAS trouve" & chr(13) 
end i f 
next 
next 

MsgBox(l i ste) 

if modif then monDocument . Store 
on Error Resume Next 
monDocument . cl ose (True) 

I On Error GoTo 0 
End Sub 

Pour un effet plus spectaculaire, faites une copie du document Codel3-02 . sxd du Zip 
telechargeable, qui contient plusieurs bibliotheques. C'est le document designe par 
Tata. sxd dans notre macro. Nous allons rechercher le mot servCrad dans les 
modules de bibliotheques. 

Le point important est d'utiliser le conteneur Basi cLi brari es du document a modi- 
fier, au lieu du conteneur BasicLibraries ordinaire, qui est celui du document qui a 
lance la macro. Le reste du codage utilise les notions indiquees a la section prece- 
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dente. La chaine de caracteres liste memorise les bibliotheques et les modules 
trouves, avec le resultat de recherche. 



Appeler un script ecrit dans un autre langage 

II est possible de lancer des scripts crees dans d'autres langages que Basic, et meme 
de lancer un script Basic (normalement depuis un autre langage, car depuis Basic ceci 
n'a pas d'interet). Dans cet exemple, on lance un script simple qui ne necessite de 
transferer aucune information vers ou depuis le script appele. 

rem Codel4-07 . odt bibli : Standard Modulel 
Option Explicit 

Sub lancerScriptsO 

' il n'existe pas de Helloworld Basic, appel d'un autre script 
si mpl eScri pt ("Ci mmi cks . AutoText . Mai n" , "Basi c" , "appl i cati on") 

Dim nouvDoc As Object 

nouvDoc = StarDesktop.~loadComponentFromURL( _ 

"private:factory/swriter" , "_blank", 0, ArrayO ) 
' ces scripts vont ecrire sur le document Writer 
si mpl eScri pt("HelloWorl d . hel 1 oworl d . js" , "JavaScri pt" , "share") 
si mpl eScri pt("HelloWorl d . Hel 1 oWorl d . pri ntHW" , "Java" , "share") 
simpleScri pt("HelloWorld . hel 1 oworl d . bsh" , "BeanShel 1 " , "share") 
simpleScript("HelloWorld.py$HelloWorldPython", "Python", "share") 
MsgBox("Cliquez OK pour fermer le document") 
nouvDoc. close (True) 
End Sub 



Sub simpleScript(nomScript As String, langage As String, _ 

emplacement As String) 
Dim mspf As Object, scriptPro As Object, monScript As Object 

mspf = createUnoService( _ 

" com. sun. star. sc ri pt. p rovider. Mas terScript Provider Factory") 
scriptPro = mspf . createScri ptProvi der("") 
On Error Goto PasScriptl 

monScript = scri ptPro . getScri pt("vnd . sun . star . scri pt : " & nomScript & 
"?language=" & langage & "&location=" & emplacement) 
' appel de script simple, sans arguments et sans resultat en retour 
monScri pt . i nvoke(Array() , ArrayO, ArrayO) 
On Error Goto 0 
Exit Sub 
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PasScri ptl : 
Resume PasScri pt2 
PasScri pt2 : 

MsgBox("Scri pt pas trouve : " & nomScript, 16) 
End Sub 

Nous avons lance des scripts qui sont fournis d'origine, dans la section Macros 
OpenOf f i ce .org, c'est-a-dire dans la branche share de l'installation. 

Notre exemple est en OOoBasic, mais on aurait pu ecrire l'equivalent dans un des 
autres langages de script supportes. 

Pour eviter l'aspect « formule magique » de l'URI d'appel du script, nous 1' avons 
decomposer en ses elements fondamentaux. La syntaxe de 1'argument nomScript est 
propre a chaque langage, vous la devinerez en comparant 1' exemple avec l'emplace- 
ment reel du script appele. Un autre moyen consiste a mettre sur un document vierge 
un bouton de formulaire, et a affecter a un de ses evenements le script souhaite. 
L'URI complete est alors visible dans le panneau d'assignation. Attention, la casse 
des caracteres doit etre respectee. 

Pour un script different de Basic, 1'argument emplacement peut prendre les valeurs : 

• user si le script est dans Mes macros ; 

• share si le script est dans Macros OpenOffice.org ; 

• document si le script est dans le meme document que le lanceur du script. 
Pour un script Basic, 1'argument emplacement peut prendre les valeurs : 

• appl i cati on si le script est dans Mes macros ou dans Macros OpenOffice.org ; 

• document si le script est dans le meme document que le lanceur du script. 

II n'est pas possible, a partir d'un document, de lancer un script appartenant a un 
autre document. 



Exemple 

Vous trouverez un exemple avec transmission de parametres sur le site OOoForum, a la section Code 
Snippets : Calling JavaScript from Basic: regular expressions 
► http://www.oooforum.org/forum/viewtopic.phtml?t=21 564 



Pour aller plus loin 

Vous trouverez plus de details dans le Developer's Guide, au chapitre Scripting Framework>How The 
Scripting Framework works. 

La documentation API de la methode i nvoke vous indiquera comment sont transmises les donnees entre 
le script et I'appelant. Elle se trouve a I'interface : com . sun . star . scri pt . provi der . XScri pt 
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Conclusion 

Gestion de fichiers Zip, connexion a l'lnternet ou envoi de courrier electronique, la 
liste ne peut etre exhaustive. Le chapitre qui s'acheve illustre la puissance mise a dis- 
position des macros par l'intermediaire de l'API. Nul besoin d'ajouter un quelconque 
composant, les outils sont directement accessibles et a la disposition du concepteur 
de macros. Ce chapitre clot l'expose et l'illustration des macros et de l'API a propre- 
ment parler. 

La partie suivante, la derniere, donne acces a de nombreux outils et ressources syn- 
thetises pour une consultation aisee. 



Annexes 




Outils et ressources 

II nous a paru indispensable de completer cet ouvrage par une annexe expliquant ce 
quest l'API et comment en obtenir des informations pour aller encore plus loin. 
Nous presentons ensuite une liste de routines utilitaires (nous en avons deja utilisees 
certaines pour simplifier nos exemples). Nous signalons egalement les ressources 
Internet incontournables pour qui souhaite se tenir a jour : il s'agit de forums oil 
chercher assistance, ou de sites fournissant des exemples de macros, des documents 
explicatifs et des outils. 



A 

Comprendre I'API 
d'OpenOffice.org 



Cette annexe offre une introduction fort utile a la principale source d'information 
officielle sur les mecanismes internes a OpenOffice.org. Tous ces documents, en 
anglais, sont accessibles a un utilisateur confirme. 



Qu'est-ce que l'API ? 

L'API (Application Programming Interface) d'OpenOffice.org est un ensemble de 
points d'entree permettant de manipuler OpenOffice.org - sans en couvrir tous les 
mecanismes. Sans etre liee a un langage de programmation particulier, elle est acces- 
sible de maniere privilegiee avec OOoBasic, mais aussi avec des langages tels que 
Java, Python, Delphi, voire d'autres outils de script tel VBscript. 

L'API est un systeme logiciel tres complexe par son etendue et par ses concepts ; elle 
est composee de tres nombreux objets heritant les uns des autres. La documentation 
des objets de l'API est organisee en un arbre dont la racine est : 

com. sun. star. 

De cette racine, elle se subdivise en modules, qui sont des groupements de pro- 
grammes, par exemple : 

com. sun. star. text. 
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Tout element de l'API se situe a un noeud de cet arbre, en juxtaposant les branches 
successives : 

com . sun . star . text . WrapTextMode . PARALLEL 

Un module se decompose en un service ou plusieurs, et parfois en sous-modules, 
comme pour le module text. 

Un service peut lui-meme comporter des services (en anglais included services). II 
peut exposer des proprietes. Ce sont des « vraies » proprietes (nous verrons plus loin 
qu'OOoBasic presente aussi des pseudo-proprietes). Un service possede en general 
une ou plusieurs interfaces. La documentation dit que le service exporte des inter- 
faces, ce qui signifie qu'il les met a la disposition du programmeur. 

Une interface contient des methodes. Ce sont des sous-programmes utilisables a 
partir de l'objet considere. Les methodes utilisent des arguments et renvoient even- 
tuellement un resultat (sous-programme fonction). Certaines interfaces contiennent 
des attributs ; un attribut s'utilise comme une propriete d'un service. 

Chaque argument et chaque resultat d'une methode, chaque propriete et chaque 
attribut peuvent etre une donnee simple ou complexe : 

• une donnee d'un type simple (booleen, entier, flottant) ; 

• une constante nommee, qui est un type entier dont les valeurs possibles sont defi- 
nies avec des noms qualifies ; 

• un objet API, donnant acces a des services, proprietes, interfaces ; 

• une sequence de donnees (elle apparait dans les langages de programmation sous 
forme d'un tableau a une dimension) ; 

• une structure de donnees, qui est un regroupement de donnees accessibles 
individuellement ; chaque element de la structure pouvant etre une donnee simple 
ou complexe. 

Comme l'API est independante du langage, le type simple indique pour une donnee 
doit etre « traduit » dans le type de donnees le plus proche pour le langage de pro- 
grammation utilise. Cela peut poser quelques difficultes : par exemple, OOoBasic ne 
possede pas de type hyper. 

Un objet API, en dehors des constantes et des structures, comporte un ou plusieurs 
services. II y a lieu de distinguer les services pris en charge, directement utilisables, et 
les services disponibles, qui peuvent etre invoques avec la methode createlnstance 
de l'objet. 
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Regies typographiques des noms dans I'API 

Les noms employes dans I'API suivent quelques regies d'homogeneite : 

• Un nom de propriete ou d'attribut debute toujours par une lettre majuscule : 
CharFontName. 

• Un nom d'interface debute par un X majuscule. 

• Un nom de methode debute en principe par un verbe (en anglais), commencant 
par une lettre minuscule : loadComponentFromURL . 

• Si un nom est compose de plusieurs mots, les mots suivant le premier debutent 
par une majuscule (sauf le premier) : createReplaceDescriptor, CharFontName. 

• Le dernier terme du nom d'une constante est entierement en majuscules : 
com . sun . star . sheet . Border . RIGHT. 



L'API reelle et I'API selon OOoBasic 

OOoBasic a plusieurs avantages par rapport aux autres langages : 

• II est le plus integre a l'application. 

• II est facile a apprendre. 

• II est concu pour simplifier l'acces aux primitives de I'API : il n'impose pas de res- 
pecter les majuscules et minuscules dans l'emploi des noms de routines et de pro- 
prietes. 

• II connait les valeurs des constantes nominees. 

• II permet d'utiliser directement les interfaces d'un objet, contrairement a C++, 
Java™ ou ses derives. 

• II permet d'utiliser comme une pseudo-propriete le couple de methodes get et 
set manipulant la meme donnee interne, contrairement a Java. 

Pour toutes ces raisons, les exemples en Java, nombreux dans la documentation, sont 
bien plus difficiles a lire que leurs equivalents en OOoBasic. A titre d'exemple, voici 
un extrait de code en Java qui modifie un mot dans un texte Writer et modifie le cur- 
seur pour ecrire en gras. 

mxDocCursor = mxDocText . createTextCursorO ; 

XSentenceCursor xSentenceCursor = (XSentenceCursor) 

UnoRunti me . query Interface (XSentenceCursor . cl ass , mxDocCursor) ; 

xSentenceCursor . gotoNextSentence (f al se) ; 

XWordCursor xWordCursor = (XWordCursor) 

UnoRunti me .query Interface (XWordCur so r . class , mxDocCursor) ; 
xWordCursor . gotoNextWord (f al se) ; 
xWordCursor. gotoNextWord(true) ; 

mxDocText . i nsertStri ng(xWordCursor , "hello ", true); 
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XPropertySet xCursorProps = (XPropertySet) 

UnoRuntime . querylnterf ace(XPropertySet . cl ass , mxDocCursor) ; 

xCursorProps . setPropertyVal ue("CharWei ght" , 

new FT oat (com . sun . star . awt . FontWei ght . BOLD)) 

Ce code Java necessite trois variables supplementaires pour gerer le curseur, une pour 
chaque interface necessaire. Voici pour comparaison le code OOoBasic equivalent, 
qui n'utilise que la variable curseur : 

mxDocCursor = mxDocText . createTextCursor 
mxDocCu rsor . gotoNextSentence(f al se) 
mxDocCu rsor . gotoNextWo rd (f al se) 
mxDocCursor . gotoNextWord(true) 

mxDocText.insertString(mxDocCursor, "hello ", true) 
mxDocCu rsor. CharWei ght = com. sun . star . awt . FontWei ght . BOLD 

Lorsqu'il existe deux methodes complementaires simples, l'une servant a affecter une 
valeur a une donnee interne, l'autre servant a obtenir la valeur de cette donnee, OOoBasic 
combine les deux sous la forme d'une pseudo-propriete, utilisable comme une simple 
variable. Voici deux codages OOoBasic qui realisent exactement la meme chose : 

Dim Taille As Object 

' codage autorise par OOoBasic 

Taille = dessin.Size 

Taille. Width = Taille. Width * 2 

dessin.Size = Taille 

' application stricte de 1 'API 
Taille = dessi n . getSizeO 
Taille. Width = Taille. Width * 2 
dessi n . setSize(Tai lie) 

L'utilisateur OOoBasic ne voit qu'une propriete Size. En realite, cette propriete 
n'existe pas, mais elle est un raccourci vers deux methodes : 

• setSize (valeur) qui modifie la taille (en anglais size) de l'objet ; 

• getSi ze() qui renvoie la taille de l'objet. 

Pour retrouver dans l'API la description d'une propriete d'objet, il est done neces- 
saire d'ajouter get ou set s'il s'agit d'une pseudo-propriete. Certaines donnees 
internes Xyz peuvent etre manipulees seulement par getXyz, ou seulement par 
setXyz. Dans ces cas, la pseudo-propriete est restreinte a la seule lecture ou ecriture. 
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On accede aux vraies proprietes des objets de l'API de maniere plus simple en OOo- 
Basic que dans d'autres langages comme Java. Exemple : 

' codage autorise par OOoBasic 
couleur = UneCellule.CellBackColor 
UneCellule.CellBackColor = RCB(255 , 255 , 204) 

' deuxieme maniere, plus complexe, et aussi valide en OOoBasic 
' ici la casse de CellBackColor doit etre respectee 
couleur = UneCellule.getPropertyValue("CellBackColor") 
UneCellule.setPropertyValue("CellBackColor", RGB(255 , 255 , 204)) 

Un objet dans une collection est accessible en OOoBasic par une indexation, comme 
si la collection etait un tableau. En realite, OOoBasic fait appel a la fonction 
getBylndex de la collection : 

' codage autorise par OOoBasic 
uneFeuille = monDocument . Sheets (1) 

' deuxieme maniere, plus complexe, et aussi valide en OOoBasic 
uneFeuille = monDocument . Sheets . getBylndex (1) 

II existe aussi un raccourci OOoBasic pour acceder par son nom a un objet de collec- 
tion. Nous ne l'avons pas employe car il peut donner des expressions ambigues. 

' codage recommande 

uneFeuille = monDocument . Sheets . getByName ("Total ") 

' deuxieme maniere, valide en OOoBasic, deconseillee 
uneFeuille = monDocument . Sheets .Total 



Aller PLUS loin Transcription entre UNO et un langage de programmation 

La technologie UNO implique certains concepts de programmation (types de donnees, gestion des 
erreurs, acces aux objets). La mise en equivalence pour un langage de programmation est appelee bin- 
ding. Le Developer's Guide decrit au chapitre Professional UN0>UN0 language bindings les regies de 
transcription pour les langages Java, C++, Basic, CLI, et I'interface COM Automation. 

Les fonctions Basic dediees a l'API 

Tout au long de cet ouvrage, nous avons utilise plusieurs fonctions OOoBasic qui 
facilitent Faeces a l'API. En void une liste plus systematique. 
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GetProcessServiceManager 

L'objet logiciel obtenu par GetProcessServi ceManager est, en quelque sorte, la mere 
de tous les objets de l'API. II permet d'obtenir un service initialise, soit par defaut, 
soit avec des arguments. Le premier cas est realise plus simplement avec 
CreateUnoServi ce. Le deuxieme cas est de la forme : 

Dim outi 1 Servi ce As Object, unService As Object 
Dim args(l) ' un ou plusieurs arguments 
outi 1 Service = GetProcessServiceManager 

1 - initialiser le tableau args() avant cette instruction - 
unService = outi 1 Servi ce.createInstanceWithArguments( 
"com. sun. star .xxx. yyy.zzz" , argsO) 

II existe aussi une troisieme forme d'initialisation : 
createlnstanceWi thArgumentsAndContextO 

Ces deux dernieres formes ne sont utilisees que dans des cas assez particuliers. 

Avec COM Automation, le Service Manager est le premier objet a obtenir. Cet 
exemple en VB.NET obtient le Service Manager, puis l'objet correspondant a 
StarDesktop. Tous les autres services en decoulent. 

Public OpenOffice As Object, StarDesktop As Object 

OpenOffice = CreateObject("com . sun . star . Servi ceManager") 

StarDesktop = OpenOf f i ce . createlnstance ("com . sun . star . frame . Desktop") 

CreateUnoService 

Cette fonction permet d'obtenir un objet capable de fournir le service donne en 
argument : 

Dim demandePasse As Object 

demandePasse = CreateUnoService ("com . sun . star . task . Interacti onHandl er") 

Cette fonction est un raccourci pour : 

Dim sm As Object, demandePasse As Object 
sm = GetProcessServiceManager 

demandePasse = 

sm . createlnstance ("com . sun . star . task . Interacti onHandl er") 
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StarDesktop 

II s'agit d'un objet predefini qui est le service de base d'OpenOffice.org. II est un rac- 
courci pour : 

Dim monOOo As Object 

monOOo = CreateUnoService("com. sun. star. frame. Desktop") 

ThisComponent 

Represents l'objet document en cours ; il est en general equivalent a : 
Dim monDocument As Object 

monDocument = StarDesktop. getCurrentComponent() 

Cependant, si l'EDI est en premier plan, CurrentComponent renverra l'EDI et la 
macro ne fonctionnera pas, alors que ThisComponent continue a renvoyer l'objet 
document. C'est pourquoi Thi sComponent est preferable. 

Notez que Thi sComponent nest pas une variable, mais un appel de fonction : s'il y a plu- 
sieurs documents OpenOffice.org ouverts, elle renvoie le document OpenOffice.org 
dont la fenetre est actuellement en avant-plan. C'est pourquoi il est preferable de ne 
l'appeler qu'au debut de la macro et de sauver le resultat dans une variable interne. 

GetDefaultContext 

Cette instruction est essentiellement utilisee pour acceder a un singleton. Elle est 
equivalente a : 

CetProcessServi ceManager . Def aul tContext 
Defaul tContext est une propriete de l'objet ServiceManager. 

Un singleton est un objet API qui ne peut exister qu'en un seul exemplaire. Void un 
exemple d'utilisation : 

dim sv As Object, repExt As String 
sv = GetDefaul tContext. getByName 

("/si ngl etons/com . sun . star . depl oyment . Packagelnf ormati onProvi der") 
repExt = sv.getPackageLocation("org.toto.test3") 
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CreateUnoStruct 

Cette fonction sert a obtenir une structure UNO a l'execution du programme, par 
exemple : 

Dim uneProp As Object 

uneProp = CreateUnoStruct("com . sun . star . beans . Property") 

Habituellement on se contente de declarer directement la variable : 
Dim uneProp As New com . sun . star . beans . Property 

CreateObject 

Cette fonction a des usages multiples. Elle peut creer une structure UNO, comme 
CreateUnoStruct. Elle peut aussi creer d'autres objets OpenOffice ; le seul cas actuelle- 
ment connu est un objet Col 1 ecti on, apparu pour une meilleure compatibilite avec VBA. 

Dim coll As Variant ' ne pas utiliser le type Object ! 
coll = CreateObject("Collection") 

La declaration directe est aussi acceptee : 
Dim coll As New Collection 

La fonction CreateObject est souvent utilisee pour etablir une connexion COM avec 
un objet externe (voir le chapitre 14). 

Dim monWord As Object 

monWord = CreateObject("Word .Appl i cation") 
' est equivalent a : 

Dim serviceCOM As Object, monWord As Object 

servi ceCOM = createUnoServi ce("com . sun . star . bri dge . ol eautomati on . Factory") 
monWord = serviceCOM. createInstance("Word. Application") 

Ici aussi, la declaration directe est acceptee : 
Dim monWord As New Word. Application 

CreateUnoValue 

Cette fonction sert a transmettre a l'API une donnee quelconque dans un type sup- 
porte par UNO. On l'emploie pour des problemes tres particuliers de conversion de 
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type de donnees vers l'API. Ici, on utilise une variable Basic d'un type Long et on la 
transmet sous forme d'un type Hyper, inexistant en Basic : 

oFile. seek(CreateUnoValue("hyper" , hxb) 

Le tableau A-l donne les equivalences entre type UNO et type Basic. Respectez la 
casse pour declarer le type UNO. 



Tableau A-1 Equivalence de types UNO et Basic 



Type UNO 


Type Basic 


bool ean 


Boolean 


byte 


Non supporte (utiliser un Integer de -128 a +127) 


short 


Integer 


long 


Long 


hyper 


Non supporte (entier a 64 bits). Compatible dans la gamme des valeurs de Long. 


float 


Single 


double 


Double 


char 


Non supporte (utiliser la valeur Unicode en Integer) 


stri ng 


String (limite a 65535 caracteres) 


any 


Variant 



L'equivalent de CreateUnoVal ue pour une programmation COM consiste a passer 
par une variable intermediate obtenue avec la methode Bridge_CetValueObject() 
du Service Manager. Voir le chapitre Automation Bridge du Developer's Guide. 



CreateUnoListener 

Permet a un programme de s'enregistrer comme auditeur d'un ensemble d'evene- 
ments. Nous en avons decrit le principe au chapitre 14. 

CreateUnoDialog 

Cette fonction sert a creer un dialogue (voir chapitre 11). Les langages non Basic 
peuvent aussi utiliser des dialogues OpenOffice, mais au prix d'instructions plus 
complexes. Reportez-vous au Developer's Guide, chapitre Graphical User Interfaces, 
section Accessing Dialogs. 
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IsUnoStruct 

Cette fonction renvoie True si la variable est une structure UNO. Citons, comme 
exemple de structure UNO, le descripteur renvoye par createReplaceDescriptor 
(voir chapitre 8). Cette fonction permet de distinguer une structure d'un objet veri- 
table, ou d'une donnee simple. 

Les variables de structure UNO sont de vraies valeurs, et non des references comme 
les variables sur les objets. C'est la raison des recopies necessaires pour effectuer une 
modification, comme par exemple ici : 

dim rognure as object 

rognure = monlmage . Graphi cCrop 

I rognure. Bottom = -2000 
monlmage. Graphi cCrop = rognure 

EqualUnoObjects 

Les variables representant des objets sont en fait des references sur 1' objet lui-meme. 
II est done possible d'avoir deux variables pointant sur le meme objet. Cette fonction 
permet de le verifier. 

HasUnoInterfaces 

Cette fonction renvoie True si l'objet en premier argument prend en charge toutes les 
interfaces listees en arguments. 

if HasUnoInterfaces(monObjet, "com. sun. star. embed. XVisualObject" , _ 
"com . sun . star . f rame .XStorabl e2") then 

Cette fonction est parfois utile pour rechercher un objet d'un type particulier dans 
une collection heteroclite. Un autre moyen est d'utiliser la fonction supportsServi ce 
d'un objet pour verifier s'il offre le service souhaite. 

ConvertToURL. ConvertFromURL 

Ces deux fonctions Basic font envie aux programmeurs utilisant d'autres langages. 
En effet, convertir une adresse Windows en URL n'a rien d'evident si l'adresse com- 
porte des espaces ou des caracteres nationaux. Pour des adresses de fichiers, ces deux 
fonctions sont equivalentes au codage suivant, qui utilise le service API 
Fi 1 eContentProvi der : 

Dim sv As Object 

Dim adrl As String, adr2 As String, adrURL As String 
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adrl = InputBox("Donnez une adresse systeme") 

sv = CreateUnoService("com. sun. star. ucb.FileContentProvider") 
adrURL = sv.getFileURLFromSystemPath("" , adrl) ' ConvertToURL 
adr2 = sv.getSystemPathFromFileURL(adrURL) ' ConvertFromURL 
' adrl doit etre identique a adr2 
MsgBox("Adresse systeme 1 : " & adrl & chr(13) & _ 

"Adresse systeme 2 : " & adr2 & chr(13) & _ 

"Adresse URL : " & adrURL) 

Un script Python importera le module uno afin d'utiliser les fonctions 
systemPathToFileUrl et f i 1 eUrlToSystemPath qui sont l'equivalent de 
ConvertToURL et ConvertFromURL, respectivement. 



La documentation de l'API et le Software Development Kit 

L'ensemble de la documentation est appele SDK (Software Development Kit), concu a 
l'origine pour un environnement de developpement en Java ou en C++. Depuis la 
version 3 d'OpenOffice.org, son contenu telechargeable a ete reduit en eliminant le 

Developer's Guide. 

Le Developers Guide est un hypertexte expliquant la conception de l'API Open- 
Office. org. II est disponible dans le wild d'OpenOffice.org a l'adresse : 

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ 
OpenOffice.org_Developers_Guide 

Ce wild permet de creer un fichier PDF de certaines parties. Mais le Developers 
Guide contient de nombreux liens vers la reference API disponible aussi en ligne, et 
reciproquement, ce qui rend une lecture interactive souvent preferable a une lecture 
imprimee. 

Le SDK est telechargeable a l'adresse http://api.openoffice.org/SDK/. C'est un execu- 
table qui installe sur votre ordinateur : 

• la reference IDL (Interface Definition Language) qui est un gigantesque hypertexte 
documentant (presque) tous les objets (au sens le plus general) de l'API ; 

• les fichiers * . i dl ayant servi a constituer la reference ; ce sont des fichiers texte ou 
on peut lire les valeurs des constantes nominees ; 

• une reference pour le developpement en Java ; 

• une reference pour le developpement en C++ ; 

• des exemples (dont ceux employes dans le Developer's Guide) ; 

• la specification des formats XML utilises ; 
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• divers outils de developpement. 

Lorsqu'on etudie cette documentation, la principale difficulte que Ton rencontre est 
quelle est concue pour un developpeur Java ou C++ charge de faire evoluer Open- 
Office.org ou d'en realiser une variante. Ce point de vue est intimement melange 
avec les descriptions des fonctionnalites disponibles, ce qui en rend la lecture assez 
difficile. De plus, et principalement dans le Developer's Guide, les exemples sont 
donnes en langage Java, notablement plus lourd que OOoBasic. 

La reference IDL est redigee par les programmeurs eux-memes lors du developpe- 
ment, et compilee ensuite automatiquement. L'ennui, c'est que les programmeurs 
sont rarement interesses par l'ecriture de la documentation. Aussi est-elle parfois 
decevante par son aspect repetitif et ses lacunes. 

Comment s'y retrouver ? 

Nous vous conseillons d'installer le SDK sur votre ordinateur, pour un acces plus 
rapide, et d'utiliser un navigateur Internet capable d'afficher de multiples pages 
accessibles sous forme d'onglets. 

Dans une installation standard sous MS-Windows, et avec la version 3 d'Open- 
Office.org, l'ensemble du SDK est installe dans le repertoire C:\Program Files\ 
OpenOffice.org 3\Basis\sdk. Dans ce repertoire, affichez dans un navigateur le 
fichier index.html. La page affichee comporte un lien vers le wild du Developer's 
Guide et un lien vers IDL Reference. 

La premiere page de la reference IDL liste les differents modules qui composent le 
module Star, l'ensemble de l'application. Tout est ensuite decompose en un arbre avec de 
nombreuses ramifications. La position d'une page dans cet arbre est rappelee en haut a 
gauche des pages (par exemple : :com: :sun: :star: :) et l'organisation des repertoires 
contenant les pages HTML reflete exactement cette hierarchic Lorsque nous indiquons 
une reference de documentation comme com. sun. star. drawing. LineProperties, 
vous afficherez la page correspondante en suivant, depuis la premiere page de 1'IDL, le 
lien intitule drawi ng, puis dans la page obtenue le lien intitule Li neProperti es, comme 
on peut le voir sur la figure A-l. 

Lautre moyen d'acces a 1'IDL, a partir de n'importe laquelle de ses pages, est d'uti- 
liser le lien Index, sur la premiere ligne du haut de la page. II vous affiche la page A 
d'un dictionnaire. Si vous cherchez la documentation sur Li neProperti es, affichez la 
page L et recherchez ce mot dans celle-ci, en debut de ligne. Vous verrez la ligne : 

LineProperties - service :: com :: sun :: star :: drawi ng : : .LineProperties 
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Ici, il s'agit d'un service dont la page de description est accessible par lien hypertexte. 
Dans bien des cas, vous obtiendrez plusieurs lignes avec le meme nom, car plusieurs 
types d'objets ayant une propriete ou une methode similaire portent normalement le 
meme nom. Ce sera a vous de determiner lequel correspond a votre contexte, grace 
aux autres informations de la ligne. 

Un dernier moyen, tres rapide, d'acceder directement a la bonne page de 1'IDL con- 
siste a utiliser l'outil XRay 



Xray 



L'API offre des fonctions dites d'introspection et de core reflection permettant 
d'obtenir a l'execution de nombreuses informations sur les objets manipules. Cepen- 
dant, ces fonctions sont assez complexes a utiliser. 
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L'outil Xray, realise avec des macros, met en forme ces informations et permet d'etu- 
dier les sous-objets. II est capable de retrouver dans 1'IDL la documentation du sous- 
objet, si elle existe. Les auteurs utilisent intensivement Xray pour etudier la structure 
des objets et lire leur documentation dans l'API. Sans Xray, cet ouvrage ne serait pas 
aussi detaille. 

Xray est un logiciel Open Source disponible en telechargement : 

• en version franfaise depuis la page http://fr.openoffice.org/Documentation/How-to/ 
indexht-programmation.html, section programmation Basic, cinquieme document, 

• en version anglaise sur OOoMacros http://ooomacros.Org/dev.php#1 01 41 6. 

Xray se presente sous la forme d'un document explicatif ecrit au format sxw car il est 
entierement compatible avec les anciennes versions d'OpenOffice.org. En cliquant 
un bouton du document, les bibliotheques de macros de Xray sont installees dans 
Mes Macros. 

Pour etudier un objet il est necessaire d'inserer une instruction dans le codage, pour 
appeler Xray en donnant cet objet en argument : 

monDocument = thi sComponent 
lesFeuilles = monDocument . Sheets 
maFeuille = 1 esFeui 1 1 es . getByName( M Danvi er") 
xray maFeuille 




Figure A- 2 

Xray : proprietes 
d'une feuille Calc 




AbsoluteName 

As i anVe r ti c alHode 

Automatic Pr intAr ea 

BorderColor 

RnttnTiRnrrlpr | 

CellBackColor 

CcllProtccCion 

CellS tyle 

Chare 01 or 

Char ton toured 

CharCrossedOut 

CharEnphasis 

CharFont 

Char FontChar Set 

fhi=irFnnr.rhi=irSptJksi an 

Char FoncChar S e tC oupl ex 

Char FontFomi ly 

Char Font Fami lyAs iaii 

Char FontFami lycomp l ex 

Char ton twame 



Doolean 
boolean 
integer 
intecrer 
integer 

integer 
integer 
integer 
integer 
string 



string 
boolean 
boolean 
long 



otruct 
string 
long 



sr.mrt 
long 



"Default" 
-1 
false 
False 



False 
False 



-l 



l 

5 
0 
0 



0 
1 




Comprendre I'API d'OpenOffice.org I 

Annexe A I 

On obtient le panneau de la figure A-2, ou on visualise les proprietes disponibles 
pour l'objet analyse. En positionnant le curseur sur la ligne d'un element affiche, il 
suffit de cliquer sur le bouton Xray pour afficher le contenu de ce sous-objet. L'ope- 
ration peut etre repetee sur differents sous-objets, a plusieurs niveaux. 

En positionnant le curseur sur la ligne d'un element, un simple clic sur le bouton 
Documentation permet de visualiser sur votre navigateur Internet la documentation 
API concernant l'objet selectionne (voir la figure A-3). Pour utiliser cette fonction, il 
faut toutefois avoir installe la documentation SDK sur l'ordinateur. 



Figure A-3 
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La figure A-4 montre les methodes offertes par l'objet en analyse. Ici l'affichage est 
en mode detaille, et en ordre alphabetique. On peut approfondir l'analyse sur une des 
methodes a condition quelle ne comporte aucun argument ou encore acceder a sa 
documentation. 

Xray vous permet de lister les services proposes par l'objet et les services disponibles 
par invocation, ou lister les interfaces prises en charge. La encore, la documentation 
d'un service ou d'une interface est directement accessible. 

II faut une certaine experience de l'API pour ne pas etre perdu dans les informations 
fournies. Comme les objets API heritent pour la plupart des proprietes et methodes 
d'un ou plusieurs autres objets, et ainsi de suite, et que vous pouvez analyser un objet 
interne a un objet, vous retrouvez certaines methodes et proprietes des « briques de 



Outils et ressources 

Annexes 



Figure A-4 

Xray : methodes 
d'une feuille Calc 
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base » d'OpenOffke.org, par exemple setDelegator, getByName, ou le tableau 
Implementationld. Certaines proprietes d'objet sont listees mais non disponibles 
dans le contexte, d'autres renvoient un objet qui n'est autre que l'objet lui-meme. 

Lorsque vous demandez la documentation a propos d'un element d'un objet, il arrive 
que la recherche echoue : la documentation manque, ou l'element est un « fossile » 
des temps revolus, ou l'objet n'est pas officiellement utilisable. 



Object Inspector 

Cet outil permet lui aussi d'explorer un objet API. II est decrit en anglais a la page 
http://wiki.services.openoffice.org/wiki/Object_lnspector. C'est une extension ecrite en 
Java. Bien que plus complexe que Xray, il est interessant pour des developpements en 
Java ou C++ grace a sa faculte de produire des portions de code. 



MRI 

Ecrit par le japonais Hanya, cet outil est caique sur Xray. II est developpe en Python 
sous la forme d'une extension qui introduit un nouveau service. II est capable de 
modifier des valeurs de proprietes et d'executer des methodes avec arguments, ce qui 
peut etre utile avec des langages qui n'ont pas la souplesse de l'EDI Basic. La docu- 
mentation est en anglais et japonais. 
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Vous trouverez MRI a la page http://extensions.services.openoffice.org/project/MRI. 



Conclusion 

Cette annexe vous a apporte les connaissances minimales pour etudier l'API. Grace a 
Xray et au SDK le developpeur pourra progressivement maitriser les nombreuses 
possibilites qu'offre l'API. 

Le chapitre suivant offre un panorama de routines utilitaires, qui complete utilement 
les techniques vues au chapitre 14. 



B 

Routines utilitaires 



La plupart des sous-programmes presentes dans ce chapitre ont ete utilises dans les 
exemples de ce livre. lis pourront vous etre tres utiles dans vos projets de macros. 



Tableaux de proprietes 

Ce que nous appelons tableau de proprietes est un tableau unidimensionnel dont 
chaque element est une structure UNO com . sun . star . PropertyVal ue. Un tel tableau 
est souvent utilise pour transmettre des informations a l'API OpenOffice.org. 

Creer un tableau de proprietes 

Le chapitre 7 utilise la fonction CreateProperties dans plusieurs exemples, notam- 
ment pour l'export PDF. Cette fonction sert a creer en une instruction un tableau de 
proprietes qui sera utilise comme argument d'une methode API, ou parfois comme 
valeur d'une propriete appartenant a un autre tableau de proprietes. Elle comporte 
un seul argument qui est un tableau Basic a une dimension, cree dynamiquement par 
la fonction Basic Array. Les arguments de la fonction Array sont, successivement, le 
nom et la valeur de chaque propriete du tableau a construire. 

rem CodeAnnexeB-Ol.odt bibli : Proprietes Modulel 
Option Explicit 
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Function CreateProperties(propLi st() As Variant) As Object 
Dim n as long, x as long 

n = UBound(propLi st) 
if n < 0 then 

CreateProperties = ArrayO 
el se 

if (n and 1) = 0 then 

MsgBox("Erreur : nombre impair d ' arguments" , 16, "CreateProperties") 
el se 

Dim p(n\2) As New com. sun . star . beans . PropertyVal ue 
for x = 0 to n\2 

p(x).Name = propLi st(2*x) 

p(x). Value = propList(2-x +1) 
next 

CreateProperties = p() 
end if 
end if 
End Function 



Acceder a une propriete par son nom 

Certains objets de l'API se presentent sous la forme d'un tableau de proprietes dont 
la liste est predefinie. C'est le cas des descripteurs de tri pour Calc et Writer. 

Ces routines adressent une propriete dont le nom est donne en argument. Rappelons 
que la casse doit etre respectee pour ce nom. La fonction hasProp renvoie True si la pro- 
priete existe dans le tableau. La fonction getPropVal renvoie la valeur de la propriete. 
La routine setPropVal affecte une valeur a la propriete. Ces deux dernieres routines 
declenchent une erreur s'il n'existe pas dans le tableau de propriete du nom indique. 

rem CodeAnnexeB-Ol.odt bibli : Proprietes Module2 
Option Explicit 

' renvoie True si une propriete existe au nom indique 

Function hasProp(descr As Variant, nomProp As String) As Boolean 
Dim p As Object 
for each p in descr 

if p. Name = nomProp then 
hasProp = True 
Exit Function 
end if 
next 

hasProp = False 
End Function 
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' renvoie la valeur de la propriete nomProp 

Function getPropVal (descr As Variant, nomProp As String) As Variant 
Dim p As Object 
for each p in descr 

if p. Name = nomProp then 
getPropVal = p. Value 
Exit Function 
end if 
next 

' la propriete nomProp n'existe pas ! 

err = 423 ' declencher erreur : Propriete ou methode introuvable 
End Function 



' affecte la valeur valProp a la propriete nomProp 

Sub setPropVal (descr As Variant, nomProp As String, valProp As Variant) 
Dim p As Object 
for each p in descr 

if p. Name = nomProp then 
p. Value = valProp 
Exit Sub 
end if 
next 

' la propriete nomProp n'existe pas ! 

err = 423 ' declencher erreur : Propriete ou methode introuvable 
End Sub 



Coordonnees de cellules 

L'API utilise des coordonnees de cellules en X et Y, debutant a zero. L'utilisateur 
emploie plutot des coordonnees alphanumeriques comme Al. 

• La fonction adrZoneStri ng renvoie la chaine de caracteres correspondant aux 
coordonnees de l'objet RangeAddress passe en argument, y compris le nom de la 
feuille. 

• La fonction adresseString effectue le meme travail pour un objet Cel 1 Address. 

• La fonction nomColonne renvoie le nom de la colonne (A, B, ... CF...) correspon- 
dant a l'index de colonne en argument. 

• La fonction indexColonne renvoie l'index de la colonne a partir de son nom (A, 
B, ... CF...) ; cela permet de clarifier les codages en utilisant explicitement les 
noms de colonne. 
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Ces fonctions declenchent une erreur si l'argument d'adresse est incorrect. 

rem CodeAnnexeB-Ol.odt bibli : Cellules Modulel 
Option Explicit 



1 renvoie 1'adresse textuelle d'une RangeAddress 

Function adrZoneString(monCal c As Object, adrZone As Object) As String 

Dim z As Object 

On Error GoTo ho rs Li mite 

z = monCalc. Sheets(adrZone . Sheet) .getCellRangeByPosition(_ 
adrZone.StartColumn, adrZone . StartRow, _ 
adrZone . EndCol umn , adrZone . EndRow) 

adrZoneString = join(split(z.AbsoluteName, "$"), "") 
On Error GoTo 0 
Exit Function 
horsLimite: 

Resume horsLimite2 
horsLimite2 : 

On Error GoTo 0 

err = 14 ' adrZone contient une valeur hors limites 
End Function 



1 renvoie 1'adresse textuelle d'une CellAddress 

Function adresseString(monCal c As Object, adrCell As Object) As String 

Dim c As Object 

On Error GoTo horsLimite 

c = monCalc.Sheets(adrCell .Sheet) .getCellByPosition( _ 
adrCel 1 .Col umn , adrCell.Row) 

adresseStri ng = join(split(c.AbsoluteName, "$"), "") 
On Error GoTo 0 
Exit Function 
horsLimite: 

Resume horsLimite2 
horsLimite2 : 

On Error GoTo 0 

err = 14 ' adrCell contient une valeur hors limites 
End Function 



' renvoie le nom d'une colonne a parti r de son numero 
Function nomColonne(monCalc As Object, X As Long) As String 
Dim uneCellule As Object 
On Error GoTo horsLimite 

uneCellule = monCalc.Sheets(O) .getCellByPosition(X,0) 
nomColonne = uneCell ul e . Col umns . El ementNames(O) 
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On Error GoTo 0 
Exit Function 
horsLimite: 

Resume horsLimite2 
horsLimite2 : 

On Error GoTo 0 

err = 14 ' X contient une valeur hors "limites 
End Function 



' renvoi e le numero d'une colonne a parti r de son nom 
Function indexColonne(monCa"lc As Object, col As String) As Long 
Dim uneCellule As Object 
On Error GoTo horsLimite 

uneCellule = monCalc. Sheets (0) . getCell RangeByName(col & "1") 

indexColonne = uneCellule. CellAddress. Column 

On Error GoTo 0 

Exit Function 

horsLimite: 

Resume horsLimite2 
horsLimite2 : 

On Error GoTo 0 

err = 14 ' col contient un nom inacceptable 
End Function 



Rechercher un objet par son nom 

La fonction Fi ndObjectByName est inspiree des travaux de Danny Brewer. Cette 
fonction recherche dans une page de dessin un objet dont le nom est donne en argu- 
ment. En cas d'echec, la fonction renvoie la valeur Nul 1 . 

rem CodeAnnexeB-Ol.odt bibli : Dessin Modulel 
Option Explicit 

' retrouve un objet a parti r de son nom 
Function FindObjectByName(unePage As Object, _ 

nomObj As String, Optional service As String) As Object 
Dim objX As Object, x As Long 
For x = 0 To unePage . Count - 1 
objX = unePage(x) 
If objX.Name = nomObj Then 
if IsMi ssi ng(servi ce) then 

Fi ndObjectByName = objX ' objet trouve 
Exit Function 
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el se 

if objX.supportsService(service) then 
Fi ndObjectByName = objX ' objet trouve 
Exit Function 
end if 
end if 
Endlf 
Next 

End Function ' renvoie Null en cas d'echec 

Le parametre service est optionnel. II permet de ne rechercher qu'un objet propo- 
sant le service indique. En effet, une page de dessin peut contenir differentes sortes 
d'objets, et vous pourriez par exemple obtenir une image ayant le nom du dessin que 
vous cherchez (par programmation, on peut donner le meme nom a plusieurs objets 
d'une page). En verifiant que 1' objet obtenu reconnait un service caracteristique du 
type d'objet recherche, nous effectuons une verification supplementaire. Le 
tableau B-l indique quel service caracterise un objet. 

Tableau B-1 Services caracteristiques 



Type d'objet recherche 


Service caracteristique 


Dessin, sauf 3D 


com . sun . star . drawi ng . Li neProperti es 


Dessin 3D 


com . sun . star . drawi ng . Shape 3DScene 


Image 


com . sun . star . drawi ng .Graphi cOb jectShape 


Objet 0LE2 


com . sun . star . drawi ng .0LE2 Shape 


Controle de formulaire 


com . sun . star .drawi ng . Control Shape 



Par exemple, pour rechercher seulement une forme dessinee appelee « F3 », nous 
ecrirons : 



Dim sv As String 

sv = "com . sun . star . drawi ng . Li neProperti es" 
maForme = Fi ndObjectByName(maPage , "F3", sv) 

En effet, le service Shape, trop general, est egalement propose par une image. En 
revanche, vous pouvez etre plus precis et exiger par exemple une Ell i pseShape. 



Redimensionner une image 

Le sous-programme resizelmageByWidth redimensionne une image a une largeur 
donnee, en gardant ses proportions. Apres insertion d'une image dans un document, 
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l'objet image fournit a travers sa propriete Graphic un objet dormant des informa- 
tions sur l'image elle-meme. Dans ce dernier objet, la structure SizePixel nous 
donne la taille de l'image en pixels. Une regie de trois nous permet d'en deduire la 
hauteur necessaire pour la largeur souhaitee. Pour modifier les dimensions, nous uti- 
liserons la propriete Si ze de l'objet image, qui possede une structure equivalente dans 
laquelle les dimensions sont mesurees en 1/100 de mm. 

rem CodeAnnexeB-Ol.odt bibli : Images Modulel 
Option Explicit 

Sub resizeImageByWidth(uneImage As Object, largeur As Long) 

Dim imagelnfo As Object, Proportion As Double, Tail lei As Object 

imagelnfo = unelmage .Graphic 

Tail lei = i magelnfo . SizePixel 

Proportion = Taillel. Height / Taillel. Width 

Taillel. Width = largeur 1 largeur en 1/100 de mm 

Taillel. Height = Taillel. Width * Proportion 

unelmage . Size = Taillel 

End Sub 



Attention 

L'image doit d'abord etre inseree dans le document pour que Graphi c fournisse des informations sur 
l'image. 



Vous pourrez facilement realiser sur ce modele un sous-programme redimensionnant 
selon une hauteur donnee. 

Autre variation, le sous-programme resi zelmageByDPI redimensionne l'image en 
respectant une densite de points. Celle-ci est exprimee en points par pouce (en 
anglais DPT). Connaissant la taille d'un pouce, on peut determiner les dimensions 
necessaires en 1/100 de mm. 

rem CodeAnnexeB-Ol.odt bibli : Images Modulel 
Option Explicit 

Sub resizeImageByDPI(uneImage As Object, DPI As Long) 

Dim imagelnfo As Object, Proportion As Double, Taillel As Object 

Const pouce = 2540 ' longueur en 1/100 de mm 

imagelnfo = unelmage .Graphic 

Taillel = i magelnfo . SizePixel 

Proportion = pouce / DPI 

Taillel. Width = Taillel. Width * Proportion 
Tail lei. Height = Taillel. Height * Proportion 
unelmage. Size = Taillel 
End Sub 
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Traduire un nom de style 

Le nom d'un style obtenu par exemple avec la propriete ParaStyl eName est le nom 
interne, en anglais. Le nom affiche dans le styliste est dans la langue locale. 

La fonction getLocaleStyl eName renvoie le nom localise correspondant a un nom 
interne. Elle emploie trois arguments : 

• l'objet document (qui contient les styles), 

• le nom de la famille de styles, 

• le nom anglais du style. 

Cette fonction ne donnera pas de bons resultats dans Impress pour les styles de la 
famille Standard (voirle chapitre 10). 

rem CodeAnnexeB-Ol.odt bibli : NomsStyles Modulel 
Option Explicit 

' renvoie le nom localise d'un style 

Function getLocaleStyl eName (leDoc As Object, _ 

fam As String, nomStyle As String) As String 
Dim uneFamille As Variant 
Dim desStyles As Object, unStyle As Object 

on Error Goto pbStyle 

desStyles = 1 eDoc . Styl eFami 1 i es . getByName(fam) 
unStyle = desStyl es . getByName(nomStyl e) 
getLocaleStyl eName = unStyl e . Di spl ayName 
On Error Goto 0 
exit function 

pbStyle: 

On Error Goto 0 

getLocaleStyl eName = "????" 
End Function 

Nous avons utilise un traitement d'erreur pour renvoyer des points d'interrogation 
sur les cas d'echec, notamment si le nom de famille de styles ou le nom de style est 
inconnu. 

Le document comporte un exemple de routine utilisant la fonction. Vous remar- 
querez que si vous entrez un nom localise, la fonction renvoie ce meme nom, grace a 
la souplesse de getByName. 
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Adresses URL de fichiers et repertoires 



Le document CodeAnnexeB-Ol.odt contient dans la bibliotheque URLaddresses plu- 
sieurs fonctions facilitant 1' analyse d'adresses de chemins de fichiers. Elles sont 
ecrites en anglais pour des raisons d'universalite. Le codage est un bon exemple de la 
puissance des fonctions Basic joi n et spl i t, signalees au chapitre 5. 

Toutes ces fonctions (voir le tableau B-2) utilisent des adresses au format URL. 
Toutes les adresses de repertoires doivent se terminer par le caractere /. 

Tableau B-2 Fonctions d'adresses URL 



getDi rectory 


Chemin d'un fichier 


Chemin du repertoire contenant le fichier 


getParentDi r 


Chemin d'un repertoire 


Chemin du repertoire parent 


getFul 1 Fi 1 eName 


Chemin d'un fichier 


Norn et extension du fichier, par exemple : 
monf i chi er . odt 


getFileNameOnly 


Chemin d'un fichier 


Norn du fichier sans I'extension, par exemple : 
monf i chi er 


getFileExt 


Chemin d'un fichier 


Extension du fichier, avec le point, par exemple : . odt 



Trier un tableau de donnees en Basic 

Les langages de script Python, Beanshell, JavaScript, disposent d'une fonction integree 
de tri, mais pas OOoBasic. La routine utilitaire Quicksort (tri rapide) effectue le tri 
d'un tableau (Array) de Vari ant. Vbici la routine principale, avec ses arguments d'appel. 

rem CodeAnnexeB-Ol.odt bibli : Trier Module2 
Option Explicit 

' myListO : tableau d' elements a trier 

' diffMm : 1 pour teni r compte de la casse 

' 0 pour ne pas teni r compte de la casse 

Sub QuickSort(myList() , diffMm As Long) 

qSort(myList() , LBound(myLi st()) , UBound(myLi st()) , diffMm) 
End Sub 

Vous trouverez le codage complet dans le fichier du Zip telechargeable. Le tri fonc- 
tionne par recursion sur la routine qSort, qui appelle la fonction parti ti on. Cette der- 
niere compare les elements deux a deux, ici avec deux appels a la fonction Basic StrComp, 
et effectue la permutation de deux elements avec une variable intermediate swapping. 
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La routine serait similaire pour trier une structure logicielle quelconque : le cceur du 
mecanisme de tri est dans le comparateur d'elements de la fonction parti ti on. 

Dans cet exemple de tri, le tableau de Variant sera en pratique un tableau de String. 

I rem CodeAnnexeB-Ol.odt bibli : Trier Modulel 
Option Explicit 

Sub exempleDeTri () 

Dim resu As String, bib As String, bi bl i sMacrosO As String 
biblisMacros = Thi sComponent . Basi cLi brari es . El ementNames 
' trier en ordre alphabetique en tenant compte de la casse 
QuickSort(biblisMacros() , 1) 

resu = join(biblisMacros() , chr(13)) 1 convertir en une chaine 
MsgBox(resu, 0, "Bibliotheques Basic de ce document") 
End Sub 

Pour de grands tableaux, l'algorithme de Tri rapide est plusieurs fois plus rapide que 
l'algorithme de Tri Shell, publie precedemment sur le site fr.OpenOffice.org. 



Rappel des routines utilitaires decrites dans le livre 

II nous a semble utile de recapituler les principales routines reutilisables que nous 
avons rencontrees au fil des chapitres du livre. 

Dialogue 

Le chapitre 11 decrit deux routines : 

• La fonction CreerDialogue cree un objet dialogue connaissant le nom de la boite 
de dialogue et sa bibliotheque. 

• Le sous-programme CenterDialog centre un nouveau dialogue par rapport a un 
dialogue pere. 

Base de donnees, formulaires 

Les routines ConnecterSource, DeconnecterSource sont decrites au chapitre 12, 
ainsi que les fonctions de transformation Apos et PointDec pour ecrire des com- 
mandes SQL bien formees. 

Les fonctions suivantes se trouvent dans le fichier CalcSQL.ods qui se trouve dans le 
repertoire regroupant les exemples du chapitre 12. 
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• La fonction CALCSQL1 sert a effectuer dans une cellule Calc une requete SQL sur 
une base de donnees. Elle renvoie un tableau de resultats. 

• La fonction CALCSQL2 importe le resultat d'une requete SQL dans une base de 
donnees. Le resultat est obtenu dans un tableau de cellules d'une feuille du 
tableur. 

La fonction Fi ndCtrl ShapeByName, decrite dans le chapitre 13, recherche dans une 
page de dessin une forme correspondant a un controle de formulaire dont le nom est 
donne en argument. 

Creation et decompression d'un fichier Zip 

Le chapitre 14 decrit une bibliotheque de gestion de fichier Zip. 

Envoyer une commande au Dispatcher 

La routine DispatchSi triple, decrite dans le chapitre 14, permet d'executer des com- 
mandes de Dispatcher qui ne necessitent pas d'argument. 



Conclusion 

Les routines exposees dans ce chapitre sont directement operationnelles. Elles illus- 
trent la notion de « re-utilisabilite » qui permet de gagner du temps et de l'energie en 
perennisant les developpements. II est inutile de recrire plusieurs fois le meme code 
pour effectuer la meme action. Creez vous-meme de telles routines ; elles constitue- 
ront petit a petit une boite a outils adaptee a vos besoins, et vous permettront de 
rester concentre sur l'objectif premier de la macro que vous etes en train de concevoir. 

Voyons maintenant quelles richesses sont disponibles sur l'lnternet. 



c 



Ressources disponibles 

sur I'lnternet 



De nombreuses informations, outils et complements sur la programmation Open- 
Office. org sont disponibles sur I'lnternet. lis sont une source toujours renouvelee de 
savoir et d'inspiration. 



Quelques conseils 

A l'attention de ceux qui n'ont pas encore l'habitude de rechercher des informations 
sur I'lnternet, voici quelques notions de base. 

Macros et extensions disponibles sur I'lnternet 

De nombreuses macros apparaissent dans des echanges sur I'lnternet, mais elles ne 
doivent pas etre considerees comme une reference absolue. Elles peuvent contenir 
des erreurs, etre ameliorees, correspondre aux premiers essais d'un programmeur ou a 
des extraits d'un codage plus complexe, etc. Cherchez done toujours a comprendre 
les principes utilises. 

Les scripts elabores et les extensions publies sur I'lnternet, comme tout logiciel, peu- 
vent comporter des bogues. Apres une installation, surveillez OpenOffice.org pen- 
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dant quelque temps afin de confirmer l'absence de perturbation et l'efficacite de 
l'extension. 

Regies de bonne conduite 

Parmi les sources d'information, nous citerons des forums web et des listes de diffu- 
sion en langue francaise, anglaise ou autres, tous gratuits. Rappelons quelques prin- 
cipes communs a tous les forums d'entraide : 

• Commencez par observer les echanges de messages avant de participer 
activement ; ceci afin de cerner le domaine des discussions et le niveau technique. 

• Cherchez par vous-meme avant de poser votre question. La meilleure reponse est 
celle que vous trouvez en ayant fourni un effort, car cela prouve que vous avez 
appris quelque chose. 

• Ne posez pas une question qui a deja recu une reponse recemment ; il existe des 
moyens de recherche dans chacun des forums. 

• Restez poli, evitez le bavardage intempestif, soyez bref et clair dans votre 
demande. 

• II est tres mal eleve de poser dans un forum une question dans une autre langue 
que celle pour laquelle il est cree. 

• N'ecrivez pas en majuscules, meme pour un titre ; c'est l'equivalent de crier. 

• Rappelez-vous que ces forums sont animes par des bonnes volontes, qui ne sont 
pas retributes pour cela. 

Utiliser une liste de diffusion 

Les listes de diffusion (mailing lists) utilisent exclusivement des messages electroniques 
(e-mails). Ces messages sont diffuses a tous les abonnes de la liste. Pour savoir com- 
ment s'abonner, envoyer un message, se desabonner, il suffit d'envoyer un courrier elec- 
tronique vide a l'adresse xxx-info@yyyy, par exemple prog-info@fr.openoffice.org. Un 
robot vous renverra un message explicatif, en anglais. Comme c'est un robot, inutile 
d'etre poli avec lui, et inutile d'esperer une reponse personnalisee. 

Void le processus d'inscription que vous devez suivre : 

1 Avec le compte e-mail sur lequel vous voulez recevoir les messages de la liste, 
envoyez un message a l'adresse xxx-subscribe@openoffice.org. Peu importe le con- 
tenu, seuls comptent l'adresse de destination et l'adresse du demandeur (la votre). 

2 Apres un certain laps de temps (quelques minutes en general), vous recevrez a 
votre adresse e-mail un message du robot. Le message est toujours en anglais. II 
vous demande simplement de renvoyer ce message depuis votre adresse e-mail. 
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En general, il suffit de cliquer le bouton Repondre sur votre logiciel de messagerie. 
Ceci a pour but de verifier que vous avez bien demande a vous inscrire. 
3 Apres un certain temps (quelques minutes en general), vous recevrez a votre 
adresse e-mail un deuxieme message du robot, avec un titre comme 
« WELCOME to xxx@openoffice.org ». Vous etes inscrit. A partir de mainte- 
nant vous allez recevoir une copie de chaque e-mail envoye sur la liste. 

Pour poser une question sur la liste, depuis le meme compte e-mail creez un message 
et envoyez-le a xxx@openoffice.org. Comme vous recevez tous les messages de la liste, 
vous recevrez votre propre message au bout de quelques minutes. 

Pour repondre a un message de la liste, utilisez le bouton Repondre de votre logiciel 
de messagerie. Ne mettez personne en copie. 

Attention 

Prenez garde aux messages de reponse automatique : si vous utilisez un repondeur automatique d'e- 
mail, vous devez I'inhiber pour les messages recus de la liste ! 

Pour vous desabonner de la liste envoyez, toujours depuis le meme compte e-mail, un 
message a l'adresse xxx-unsubscribe@openoffice.org. Le processus est similaire a 
l'inscription : vous recevez un message en retour, vous confirmez en y repondant, et 
vous recevez finalement un message ayant pour titre « GOODBYE from to 
xxx@openoffice.org ». 



Ressources en francais 

Le site fr.OpenOffice.org 

Ce site incontournable se trouve a l'adresse http://fr.openoffice.org/. Vous y trouverez 
une section pour telecharger le logiciel OpenOffice.org, et une section Documentation. 

Dans la page Documentationhttp://fr.openoffice.org/Documentation/lndex.html, vous 
trouverez des liens vers des pages du domaine de la programmation ; suivez les liens 
nommes Guides, Macros, Exemples, Outils et Jeux, Programmation. 

La page Programmation liste des manuels (HowTo). Certains font double emploi avec 
notre ouvrage ou sont cites ailleurs, mais nous signalerons ceux apportant des infor- 
mations complementaires. 

• Dans la jungle de I'API : une experience vecue d'un essai de comprehension de 
1API, racontee sur le mode humoristique. 
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• Exemples pour BDD : divers conseils de programmation Basic sur les bases de don- 
nees et formulaires. 

• Manuel de programmation Basic StarOffice 8 : ce document ecrit par Sun fournit une 
autre vision de la programmation de StarOffice, un derive d'OpenOffice.org. 
Vous y trouverez une description succincte, mais couvrant l'ensemble OOoBasic 
et API, avec quelques informations non decrites dans cet ouvrage ainsi que des 
conseils pour un programmeur VBA. 

La meme page Programmation permet aussi de telecharger quelques outils, dont Xray 
et des boites a outils pour COM. 

Dans la page des Guides, accessible depuis la page principale du site, vous trouverez le 
document Elements de programmation des macros dans OOo. C'estla traduction francaise 
d'un document anglais ecrit par Andrew Pitonyak. II contient un grand nombre de 
« recettes » sur des aspects assez specialises de la programmation OpenOffice.org. La 
traduction etant tres en retard sur le document original, consultez plutot la version 
anglaise sur son site. Vous y trouverez aussi un document sur les bases de donnees. 



► En francais : http://fr.openoffice.org/Documentation/Guides/lndexguide.html 

► En anglais : http://www.pitonyak.org/oo.php 



Le forum de la communaute francophone 

Le forum francais de la Communaute OpenOffice.org http://user.services. 
openoffice.org/fr/forum/ est recent et facile a utiliser. Toutefois, veillez a lire et observer 
les regies du forum et les messages en Post-it avant de poser une question, sinon vous 
vous ferez rappeler a l'ordre. II est conseille de poster un petit fichier, ou une copie 
d'ecran, pour expliciter votre probleme. 

La section Macros et API est utilisee pour toutes les questions de programmation. 

La section Supreme de Code collectionne des codages de reference. La section Exten- 
sions indique des extensions considerees comme particulierement utiles. 

Et ne manquez pas de visiter la section Tutoriels. 

Les listes de diffusion francophones 

Le site francais d'OpenOffice.org, http://fr.openoffice.org/ gere plusieurs listes de dif- 
fusions. Lisez la page http://fr.openoffice.org/contact-forums.html qui vous donnera 
toutes informations utiles. Les questions concernant la programmation et 1API sont 
posees dans la liste prog@fr.openoffice.org. 
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Le site The Mail Archive vous permet de consulter sur un navigateur web les messages 
deja passes sur certaines des listes de diffusion. Par exemple pour la liste prog, voyez 
http://www.mail-archive.eom/prog@fr.openoffice.org/. 

Autres sites 

Le site http://oooconv.free.fr/ cree par Laurent Godard presente plusieurs outils dont 
l'analyse sera instructive : OOoConv, FitOO, BatchConv. 



Ressources en langue anglaise 

Le forum de la communaute anglophone 

Le forum anglais de la Communaute OpenOffice.org http://user.services. 
openoffice.org/en/forum/ est recent, il utilise le meme moteur de forum que son equi- 
valent francais. Les questions de programmation sont posees dans la section Macros 
and UNO API ou une de ses sous-sections. Les exemples de codage sont dans la section 
Code Snippets. 

Le forum OOoForum 

Le forum http://www.oooforum.org/ a un trafic important (et malheureusement par- 
fois envahi de spams). On y trouve en particulier la section Macros and API, ou on pose 
des questions sur la programmation et ou vous trouverez de nombreuses informa- 
tions dans les reponses deja publiees. La section Code Snippets est un repertoire 
d'exemples de codage. 

Les listes de diffusion anglophones 

Les listes de diffusion anglaises concernant la programmation sont gerees par diffe- 
rents projets de la communaute OpenOffice.org. Le tableau C-l indique les listes 
interessantes pour un programmeur. Les chefs developpeurs d'OpenOffice.org inter- 
viennent ici dans la mesure de leur disponibilite. Abstenez-vous d'y poser des ques- 
tions de debutant. 

Le site GMANE permet de consulter facilement des listes de diffusion sans y etre 
abonne. Allez a la page http://gmane.org/find.php et indiquez le nom de la liste sou- 
haitee, par exemple dev@api.openoffice.org. 
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Tableau C-1 Listes de diffusion anglaises 





dev-subscribe@openoffice.org 


Developpement, en general. Trap nombreux messages pour 
etre utile. 


dev-subscribe@api.openoffice.org 


Questions concernant I'API. 


dev-subscribe@udk.openoffice.org 


Questions sur le mecanisme de script et sur les langages de 
script. 


dev-subscribe@extensions.openoffice.org 


Questions sur le developpement d'extensions. 


dev-subscribe@dba.openoffice.org 


Questions concernant les bases de donnees. 


dev-subscribe@framework.openoffice.org 


Questions sur la structure interne d'OpenOffice.org. 


allfeatures-subscribe@openoffice.org 


Annonce devolution de I'API. Liste en lecture seule. 


interface-announce-subscribe@openoffice.org 


Annonce de changement d'interface. Liste en lecture seule. 


releases-subscribe@openoffice.org 


Annonce des versions de developpement d'OpenOffice.org. 



Autres sites 



Sites de developpement OpenOffice.org 

Le site du projet API http://api.openoffice.org/ donne acces aux documentations de 
reference, en particulier le Developer's Guide, le SDK et des liens vers le wild. II publie 
aussi des snippets fournis par les programmeurs API : http://codesnippets. 
services.open-office.org/ 

Pour les programmeurs aguerris, le site du projet UDK d'OpenOffice.org http:// 
udk.openoffice.org/ est consacre aux developpements permettant de programmer 
OpenOffice.org dans differents langages, dont OOoBasic. II fournit differents liens 
et des pages explicatives. Les possibilites de recherche tees puissantes de la page http:/ 
/svn. services.openoffice.org/opengrok/ donnent un acces direct au code source de diffe- 
rentes versions. 

Le site OOoMacros 

Le site de langue anglaise http://ooomacros.org/ contient de nombreuses macros, la 
plupart assez, voire tees elaborees. On y trouve notamment des macros ecrites par 
Danny Brewer, qui sont des modeles de bonne programmation. Vous y retrouverez 
aussi certaines macros francaises publiees en version anglaise. 

L'entrepdt des Extensions 

Le site http://extensions.services.openoffice.org/ vise a regrouper toutes les extensions 
pour OpenOffice.org. C'est done le site a utiliser pour heberger vos extensions desti- 
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nees a la communaute. Bien que la plupart des extensions proposees soient gratuites 
et Open Source, certaines sont payantes ou avec une licence plus limitative. 



Les sites pour telecharger OpenOffice.org 

Les sites miroirs d'OpenOffice.org contiennent les fichiers de l'application Open- 
Office. org en differentes langues et pour differents systemes d'exploitation. lis sont 
repartis sur le monde entier et on y accede en protocole http ou en ftp. Leurs struc- 
tures sont identiques. 

Les serveurs « etendus », en petit nombre, contiennent en plus les versions de deve- 
loppement et le SDK. Les serveurs d'archives conservent les versions anciennes 
d'OpenOffice.org. 

Les pages web de telechargement d'OpenOffice.org, faites pour un acces simplifie a 
la version officielle, ne sont pas pratiques pour obtenir tous les fichiers disponibles. 
Utilisez plutot un client FTP comme FileZilla pour acceder aux serveurs FTP 
miroirs d'OpenOffice.org et choisissez de preference un serveur proche. Le 
tableau C-2 donne une selection, la liste complete des sites miroirs se trouve a la page 
http://distribution.openoffice.org/mirrors/. 

Tableau C-2 Quelques serveurs FTP 



ftp://ftp.free.fr 


Etendu 


France 


/mi rrors/ 

ftp . openof fi ce .org/ 


ftp://ftp.belnet.be 


Normal 


Belgique 


/pub/mi rror/ 

ftp . openof fi ce .org/ 


ftp : //openof f i ce .cict.fr 


Etendu 


France 


/openof fi ce/ 


ftp://openoffice.mi rror. rafaf .ca 


Normal 


Canada 


/openof fi ce/ 


ftp: //mi rror . swi tch . ch 


Etendu 


Suisse 


/mi rror/OpenOf fi ce/ 


ftp: //openof fi ce .mi mors . tds . net 


Etendu 


USA 


/pub/openof f i ce/ 


ftp : //ftp . rz . tu-bs . de 


Etendu 


Allemagne 


/pub/mi rror/ 
OpenOff i ce .org/ 


ftp : //ftp . sunet . se 


Etendu 


Suede 


/pub/Office/ 
OpenOffice.org/ 


ftp : //archi ve . servi ces . openof fi ce . org 


Archives 


USA 


/pub/openoffi ce-archi ve/ 
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Ou se trouvent les langpacks ? 

Pour disposer d'une version OpenOffice.org multilingue au niveau de l'interface uti- 
lisateur, il est necessaire d'installer un paquet linguistique (en anglais langpack) pour 
chaque langue. 

Comme vous aurez probablement besoin de l'interface anglaise (US), le plus simple 
est de commencer par telecharger la version complete d'OpenOffice.org dans cette 
version. Elle se trouve dans la branche stabl e/ du repertoire dedie a OpenOffice. 
Telechargez ensuite les langpacks. lis se trouvent en general dans les sous-repertoires 
de la branche 1 ocal i zed/. Pour certaines langues, le langpack n'est disponible que sur 
les serveurs « etendus », dans le sous-repertoire extended/ ou se trouvent les versions 
de developpement. 



IssueZilla 

Aussi appele aussi en abrege IZ, IssueZilla est une base de donnees permettant de 
gerer les rapports d'anomalies (en anglais issue) et de demandes d'amelioration. Elle 
est consultable sur l'lnternet. Les rapports IssueZilla sont rediges en anglais, afin 
d'etre comprehensibles par les lecteurs du monde entier. II est done necessaire de 
connaitre cette langue pour utiliser cette source d'information. 

Rechercher un rapport dans IssueZilla 

La page d'entree pour rechercher quoi que ce soit dans IssueZilla est : 
http://qa.open-office.org/issues/query.cgi 

Chaque rapport IssueZilla recoit un numero. Pour afficher un rapport dont on con- 
nait le numero, il suffit de remplir le champ en haut de la page et de cliquer sur le 
bouton Jump to Issue. 

Si vous cherchez s'il existe un rapport sur un sujet donne, il faut remplir certains 
champs proposes par le formulaire. Plus vous remplissez de champs, plus la 
recherche se focalise. La difficulte est de se demander quels mots ont pu etre utilises 
dans les rapports deja ecrits. Pour eviter des recherches infructueuses, il est preferable 
de commencer par une recherche assez generale, un mot ou deux dans le titre du rap- 
port, et de restreindre la recherche si elle renvoie un grand nombre de rapports. Sou- 
vent il faut essayer des synonymes. 
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Rediger un rapport 

De nombreux rapports sont ecrits chaque jour et les developpeurs ont du mal a les 
analyser. Vous ne devriez en ecrire que sur un sujet que vous estimez important et 
faire une recherche prealable pour eviter de dupliquer un rapport existant. 

Attention 

On peut ecrire un rapport pour seulement deux raisons : demander une amelioration ou signaler une 
anomalie. IssueZilla n'est pas un site pour demander de I'aide, voyez les forums pour cela. 

Avant d'ecrire un rapport d'anomalie, verifiez tres soigneusement qu'il s'agit bien 
d'une erreur de l'application OpenOffice.org et non pas d'une erreur de comprehen- 
sion de votre part, ou d'une mauvaise configuration de votre ordinateur. Simplifiez 
au maximum les conditions d'apparition de l'anomalie. Joignez si possible un docu- 
ment demontrant 1' erreur, par exemple une macro reduite au codage minimum 
necessaire. En effectuant ce travail, vous analyserez mieux l'anomalie (et souvent 
vous verrez quelle provient d'une erreur de votre part). Soyez le plus clair possible 
dans les explications, restez factuel. Pensez que les developpeurs ont a lire des 
dizaines de rapports, en plus de leur activite habituelle. 

L'ecriture de rapports est reservee aux membres d'OpenOffice.org. Ce n'est pas une 
societe secrete, n'importe qui peut devenir membre, gratuitement et sans engage- 
ment. Allez a la page http://www.openoffice.org/servlets/Join et remplissez le formu- 
laire. Vous avez maintenant une identite dans le systeme et un mot de passe. 

Pour creer un rapport, vous devez d'abord vous connecter au systeme, en allant a la 
page http://www.openoffice.org/servlets/TLogin. Puis, commencez a la page http:// 
qa.openoffice.org/issue_handling/pre_submission.html. Une fois choisi le domaine prin- 
cipal, vous vous retrouvez devant un formulaire dont il faut remplir au mieux les 
cases. Ce n'est pas facile les premieres fois. Le titre du rapport et le texte explicatif 
doivent obligatoirement etre en anglais. Envoyez le rapport. Un numero lui sera 
attribue automatiquement et vous recevrez un courrier electronique a chaque evolu- 
tion de ce rapport. Utilisez la page web renvoyee pour aj outer eventuellement un 
fichier. Plus tard, en reaffichant le rapport, vous pourrez ajouter de nouvelles infor- 
mations, a condition de vous etre identifie. Soyez tres patient, un rapport peut rester 
plusieurs mois sans reponse... 

Les demandes d'amelioration et rapports d'anomalies sont lus par les developpeurs et 
classes avec un horizon de prise en compte eventuelle (Target Milestone). Ceci ne 
veut pas dire qu'elles seront introduites, car d'autres criteres entrent en jeu (res- 
sources, interet marketing, complexite). II arrive souvent que la date previsionnelle 
soit reportee a plus tard, faute de temps. 
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Partager la connaissance 

Comme nous l'avons vu dans 1' expose precedent, la communaute est tres active en ce 
qui concerne l'API et les macros. De nombreuses sources sont disponibles et il ne 
tient qua nous, acteurs et utilisateurs, d'enrichir notre connaissance commune. 

Vous venez d'ecrire une macro qui comble un manque d'OpenOffice.org ou simple- 
ment se revele utile au jour le jour ; il est fort probable que cette macro puisse servir a 
quelqu'un d'autre. Comme nous apprenons tous de la lecture des macros publiees par 
d'autres, vous pouvez vous aussi participer en rendant public votre travail. 

Pour que les listes de diffusion et forums d'aide soient utiles, il faut que des lecteurs 
repondent aux questions. C'est une activite purement benevole et altruiste, qui nest 
pas reservee aux specialistes. II y a des questions de debutant et des questions com- 
plexes, mais aussi des questions sur un sujet que vous connaissez bien. Alors, lancez- 
vous si vous pensez avoir une solution. Votre contribution sera appreciee et vous 
apprendrez vous-meme en etudiant ces problemes. Pourquoi s'en priver ? 



Conclusion 



La richesse des ressources disponibles sur l'lnternet, source d'informations dyna- 
mique et vivante, est illimitee et nous n'en presentons qu'une partie. N'hesitez pas a 
en tirer regulierement profit. 
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selection 516 
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proprietes 513 
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message 198 
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880 



Programmation OpenOffice.org - Macros OOoBASIC et API 



evenement 25, 639 

formulaire 762 

RowSet 719 
Evenements, onglet 586 
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exception 201 
Exit Function 148 
Exit Do 130 
Exit For 128 
Exit Function 192 
Exit Sub 143, 192 
Exp 162 

exponentielle 162 
exportation 232 
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extension 24, 31, 34, 53, 783 
Extension Compiler 37 
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F 
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fermer OpenOffice 810 
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texte 181, 793 
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FileAttr 186 
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FilePicker 656 
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FilterName 219, 233 
FilterOptions 219, 245 
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CSV 242 
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FolderPicker 656 
fonction 
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graphique 802 
Green 176 
grille 

formulaire 756 
guillemet 79 

H 

hasard 162 
HasByName 268 
hasLocation 221 
hasProp 856 

HasUnoInterfaces 172, 846 
Hex 167 
Hidden 218 
Horijustify 414 
HoriOrient 347 
HoriOrientRelation 347 
Hour 171 
hyper 838 

I 

IDE voir EDI 43 

IDL 847 

If Then Else 117 

Hf 123, 125 

image 

exporter 247 
proprietes 564 
redimensionner 860 

imbrication 118, 127 

imp 89 

importation 232 
Impress 

configuration 580 

imprimer 580 

page 

de notes 578 
prospectus 579 

style 579 
imprimer 226 

options 230, 393 
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boucle 127 
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limite 104 

valeurs extremes 101 
indexColonne 857 
Input 181 
InputBox 174 

insertControlCharacter 434 
insertNewBylndex 500 
insertNewByName 398 
InStrl58 

instruction non execut.ee 191 
Int 169 
Integer 81 

InteractionHandler 215, 217, 
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interception d'erreur 190 
interface 838 
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IsArray 96, 171 
IsDate 96, 171 
IsEmpty 96, 171 
IsMissing 138, 171 
isModified 220 
IsNull 96, 171 
IsNumeric 96, 172 
IsObject 96, 172 
IsUnoStruct 172, 846 

J 

Java 13, 44, 839 
JavaScript 13 
Join 160 

K 

Kill 177 
L 

lancer un programme 187 
langpack 650, 874 
Language (propriete) 253 
langue 253, 783 

dialogue 650 

message 653 
LayerManager 508 
LBound 104, 141 
Lease 170 



Left 159 
Len 156 
LF167 
Licence IX 
lien 

DDE 469 

hypertexte 383 
ligne 65 

de commande (executer une 
macro) 26 

longueur 65 

proprietes 521 
LIKE 695, 718 
Like 156 
Line Input 183 
Linejoint 522 
LineStyle 521 
lire un fichier 181 
liste 

de diffusion 868 

remplir 633, 637 
Listener 471, 578, 719, 762, 

820, 823, 826 
loadComponentFromURL 211 
loadLibrary 150 
Locl86 
Locale 253, 783 
lockControllers 801 
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Log 161 

logarithme neperien 161 
Long 81 
Loop 130 
LSet 161 
LTrim 159 

M 

MacroExecutionMode 216 
mailing 727 
Map AppFont 586 
MasterPages 503 
menu 811 

message d'erreur 198 
methode 201, 208, 838 
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Mid 159 

Minute 171 

mise au point 59 

MkDir 177 

modele 219, 627, 741 

de document 218 
module 50 

creer 55 

deplacer 54 
monetaire (variable) 84 
Month 171 

mot de passe 213, 396, 596, 678 
moveByName 400 
moveRange 443 
MsgBox 172 

N 

Name 397, 499 
Name (fonction) 177 
NamedRanges 407 
Next 127 

niveau de securite 5 
nom 

routine 66 

variable 66 
nombre 

aleatoire 162 

hexadecimal 167 

octal 167 
nomColonne 857 
non imprimable 

caractere 166 
not 88, 90 
Nothing 93 
Now 162 
Null 95 

Null (valeur) 709 

o 

Object 93, 208 
objet 

UNO 208 

utilisation incorrecte 200 
Oct 167 



OLE 383, 860 
ombre 

position 289 
On Error GoTo 190 
On Error Resume Next 193 
On Goto 134 

On Error GoTo etiquette 193 
OOoBasic 43 
Open 181 
operateur 
booleen 88 

ordre d'evaluation 92 
de comparaison 89, 90 

ordre d'evaluation 92 
numerique 86 

ordre d'evaluation 87 
Option Base 116 
Option Compatible 

(declaration) 45 
Option Explicit 74 
Option VBASupport 46 
Optional 138 
or 88, 90 
ordre 

d'activation 606, 608, 609 
d'evaluation 86, 91 

P 

page de dessin 

couche 384 

propriet.es 513 
palette des couleurs 799 
paragraphe 281, 288 

proprietes 287 
parametres 

appel de sous- 
programme 136 

optionnels 137 
paraStyleName 286 
parentheses 66 
Password 215 
PATH 783 
pays 253, 783 
PDF 236, 237, 241, 242 



Pi 161 

pile des appels 62 
Point (structure) 515 
point d'arret 60 
PointDec 696 
pointeur 105 
portee des variables 77 
Preserve 103 
Print 174, 181 
Printer 226 

Private 77, 99, 102, 135 
procedure 

de fonction 201 
Property Value 213, 241, 250 
propriete 201, 208, 838, 841 

de caractere 290 

de paragraphe 287 

diagramme 479 

valeur incorrecte 200 
pseudo-adresse 219 
pseudo-propriete 208, 838, 839, 
840 

pseudo-variable 148 
Public 78, 99, 102, 135, 153 
publipostage 727 
Put 181 
Python 17 

Q 

queryEmptyCells 439 
R 

raccourci clavier 21 
racine carree 162 
radian 161 
Random Access 185 
Randomize 162 
rapport 776 

d'anomalie 874 
ReadOnly 215, 261 
recherche 

attribut particulier 308 

descripteur 307 

limiter 309 
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recursion 179 
Red 176 
Redim 102 
REM 64 
Remove 110, 501 
removeActionLock 802 
removeByName 268, 399 
remplacement 

descripteur 313 
repertoire 177 
Replace 160 
replaceAll 450 
Reset 186 
residente 26 
resizelmageByDPI 861 
resizelmageByWidth 860 
Resume 191, 193 
Resume etiquette 192 
Resume Next 191 
Return 144 
RGB 175 
Right 159 
RmDir 177 
Rnd 162 
routine, nom 66 
Rows 324 
RSet 161 
RTrim 159 

S 

sauver 221 

SDK 847 

Second 171 

section, proprietes 358 

securite 

chiffrer le contenu des 
macros d'une 
bibliotheque 50 

document protege 213 

et macro 5 

executer quel que soit le 

niveau 216 
mot de passe de 

bibliotheque 54 



niveau 5 

source de confiance 8 
Seek 186 
Select Case 121 
Separator Line VerticalAlignme 

nt 352 
sequence 838 
serial number 170 
serveur OpenOffice.org 873 
service 838 
SetAttr 181 
setPropertyValue 841 
setPropVal230, 337, 453, 856 
setXxx 706 
Sgn 161 

ShadowFormat 289, 416 
Sheets 396 
Shell 187, 799 
signature numerique 9 
Sin 161 
Single 82 
singleton 843 
Size (structure) 514 
soffice 47, 50, 149 
Source 266 
sous-formulaire 755 
sous-programme 134, 135 

argument 135, 138 

Exit Sub 143 

par reference 139 

par valeur 139 

parametres 139 
d'appel 136, 139 
optionnels 137 

simplifier 137 

Sub 148 

tableau en parametre 140 
traitement d'erreur 202 
variable 141 

Space 160 

Split 160 

SQL 694 

Sqr 162 

Standard 50 



StarBasic 43 

StarDesktop 210, 231, 843 
Static 142 
Step 127, 649 
Stop 132 
store 221 

storeAsURL 221, 222 
storeToURL 222, 241 
Str 167 
StrComp 156 
String 79, 279 
String (fonction) 160 
structure 838 
chainee 113 
UNO 

bordure 289, 417 
CellAddress 405 
CellRangeAddress 406 
Date 702 
DateTime 702 
definition 207 
Locale 253 
Point 515 
Rectangle 647 
Size 514 
Time 702 
style 266 
creer 269 
famille 267 
modifier 270 

option de chargement 269 
recuperer 268 
Sub 135 

supportsService 285, 408, 846 
surlignement 291 
Surround 351 
Switch 126 
syntaxe 61 

adresse de fichier 176 

T 

tableau 99 
bordure 421 
colonne 426 
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structure 352 

contenu 335 

copier 105 

de proprietes 855 

de tableaux 107 

de Variant 106 

inserer 316 

irregulier 108 

largeur 323 

ligne 325, 425 

multidimensionnel 101 

passer en parametre 140 

positionnement 323 

proprietes 319 
cellule 332 

redimensionner 102 

supprimer 318 

tri par colonne 337 

unidimensionnel 100 

Variant 106 
TableBorder 320, 421 
TableColumnSeparators 326 
tabulation 64, 167 

constante d'alignement 306 

definir 304 
Tag 629, 631, 632, 748, 755 
Tan 161 

taquet (composante) 305 
temoin 59 
template 218 
TextColumns 351 
textfield.HiddenParagraph 375 
TextFieldMasters 372 
ThisComponent 210, 843 
Time 162 
Timer 162 
TimeSerial 92, 170 
Time Value 171 
to 101 

traitement d'erreur 132 
tri 717, 863 
Trim 159 
True 87 
twip 586 



TwipsPerPixelX 186 
TwipsPerPixelY 186 
type 

caracteres 114 

conversion automatique 164 
declaration 114 
entier 81 

instruction de definition 115 
Mime 248 
reel 82 

utilisateur 111 
TypeName 97, 98 

U 

UBound 104, 141 
Ucase 170 
UDT 111 

Unicode 79, 90, 166 
unlockControllers 801 
UNO 200 
unopkg 34 
UpdateAll 389 
UpdateDocMode 217, 218 
updateXxx 707 
URE (UNO Runtime 

Environment) 780 
URL 211, 672 
User Defined Type 111 

V 

Val 166 
variable 73 
nom 66 

non declaree, type 114 
non definie 198 
numerique 81 
objet non definie 198 
parentheses 67 
portee 141 
sous-programme 141 
statique 142 
test de contenu 171 
valeur initiale 76 
Variant 94, 96, 253 



VarType 97, 98 

VBA 45, 76, 77, 85, 736, 739, 

820, 870 
vecteur 100 
Vertjustify 415 
VertOrient 348 
VertOrientRelation 349 
ViewController 266 

w 

Wait 162 
WeekDay 171 
Wend 131 
While 131 
Windows 815 

With 256, 305, 307, 350, 697 

Write 181 

Writer 

bookmark 378 
cadre 342 

ancrage 346 

bordure 351 

constante 345 

curseur 354 
caractere 

accentuation 292 

casse 293 

clignoter 296 

contour 296 

couleur 294 

exposant 294 

formatage 
local 290 
supprimer 297 

indice 294 

italique 291 

Locale 296 

ombre 296 

police 296 

proprietes 290 

relief 293 

souligne 291 

style 296 

taille 296 
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champ de texte 365 
curseur 300 

de cellule 281 

definir 298 

methode de 

deplacement 303 

visible 281 
en-tete 363 
espace insecable 281 
formater 285 
forme 281 
hypertexte 382 
image 388 

impression, options 393 
inserer texte 279 
note 367 

page de dessin 384 
paragraphe 281 

masque 282 

rechercher 315 

supprimer 283 
pied de page 363 
rechercher, paragraphe 315 
remplacer, texte 312 
retour a la ligne 281 
saut 

de colonne 282 

de ligne 280 



de page 281 
section 354 
selection 299 
separateur de mots 390 
signet 378 
statistiques 390 
style 359 

appliquer 285 

bordure 360, 364 

cadre 365 

caractere 286, 359 

numerotation 365 

page 360 

paragraphe 359 
tableau 316 

bordure 320 

bordure de cellule 332 

cellule, proprietes 332 

colonne 326 

curseur de cellule 329 

formule dans une 
cellule 334 

ligne 324 

trier 336 

zone selectionnee 331 
tabulation 280, 304 
taquet de tabulation 304 
texte 306 



conditionnel 377 

masque 375 

remplacer 312 

selection 299 
tiret 

conditionnel 281 

insecable 281 
zone de texte 276, 278, 297 

X 

xor 88, 90 
Xray 820, 849 

Y 

Year 171 
Z 

Zip 796 
zone 

de cellules 435, 472 
deplacer 443 
fonction 

mathematique 440 
de liste, modifier 633 
enumerer les cellules 436 
nommee 407 
zoom 270, 271 



Programmation 

OpenOffice.org 3 

Suite bureautique libre, gratuite et multi-plate-forme, OpenOffice.org comporte plusieurs langages de script dont 
OOoBasic. Elle est egalement munie d'une API permettant de manipuler ses objets. Automatisable et extensible, elle 
s'integre parfaitement au systeme d'information de I'entreprise. 

Le livre de reference sur la programmation OpenOffice.org et StarOffice 

Ecrit par deux contributeurs majeurs de la communaute francophone fr.DpenOffice.org, ce livre est une reference 
incontournable sur le puissant langage de macros OOoBASIC et sur I'API d'OpenOffice.org. II explique comment 
utiliser I'interface utilisateur liee aux macros et aux scripts afin d'automatiser des taches repetitives, mais aussi 
comment tirer parti du langage de OOoBasic pour manipuler des documents, creer des boTtes de dialogue et des 
formulaires, exploiter des bases de donnees externes ou integrees, intercepter des evenements. Chaque point de 
I'API est decrit grace a de nombreux exemples de macros et de routines reutilisables. 

IMouveautes liees a la version 3.1 d'OpenOffice.org 

En plus des fonctions de programmation d'OpenOffice.org 2, ce livre couvre les nouveautes de la version 3.1 : Document- 
Properties, surlignement, notes et tableaux irreguliers dans Writer, gestion de diaporama dans Impress, integration des 
macros dans Base, jusqu'aux fonctions peu connues, sans oublier I'exportation PDF, I'export et import de texte encode, 
le filtrage de donnees, en passant par les fonctions matricielles et la gestion d'evenements. La creation de boTtes de 
dialogue ergonomiques et multilingues est expliquee ainsi que les controles de formulaire et les formulaires integres. 



Au sommaire 

Les scripts • Niveaux de securite • Enregistrer et executer une macro • Langages de script • Extensions • OOoBasic • 
Gerer les bibliotheques • EDI • Types de donnees, tableaux, structures • Instructions conditionnelles, sous-programmes 

• Instructions de traitement • Traitement d'erreurs • Les documents DpenOffice.org • Ouvrir, enregistrer, imprimer, 
fermer • Filtres d'import/export • Proprietes de document • Formats de nombre • Styles • Configuration • Writer 

• Zone de texte, curseurs • Inserer du texte, le mettre en forme • Rechercher, remplacer • Tableaux • Cadres • 
Sections • Champs de texte • Signets et renvois • Formes et images • Imprimer • Calc • Feuille, cellule, zone, ligne, 
colonne • Lire, modifier une cellule • Deplacer, recopier • Rechercher, remplacer • Trier, filtrer • Fonctions pour Calc 

• Liens • Diagrammes • Styles • Formes et images • Imprimer • Draw et Impress • Page, arriere-plan, couche • 
Inserer une forme • Proprietes des formes • Types de formes • Points de colle • Grouper des formes • Inserer des 
images • Objets 0LE2 • Specificites d'lmpress par rapport a Draw • Diaporamas • BoTtes de dialogue • Construire 
un dialogue avec I'EDI • Aspects ergonomiques • Les champs de saisie • Evenements • Pages multiples • Dialogues 
multilingues • Dialogues de I'API • Sources de donnees • Le concept Base • Les sources de donnees • Se connecter • 
Acces par SQL, par ResultSet, par RowSet • Trier, filtrer • Transactions • Publipostage • Formulaires • Les controles • 
Controles et base de donnees • Evenements • Macros et document Base • Formulaires et document Base • Techniques 
auancees • Repertoires d'installation • Lire et modifier la configuration • Les fichiers et I'API • Aspects utilisateur • 
Le Dispatcher • Methodes propres a MS-Windows • Comprendre I'API • L'API depuis OOoBasic • La documentation 
API • Xray • Routines utilitaires • Ressources de I'lnternet • Listes de diffusion • Forums • IssueZilla. 



A qui s'adresse cet ouvrage ? 

- Aux utilisateurs d'OpenOffice.org et StarOffice souhaitant automatiser et etendre leur suite bureautique ; 

- A ceux qui migrent vers OpenOffice.org et souhaitent recreer des macros existantes ; 

- Aux developpeurs d'applications d'entreprise et services informatiques ayant a integrer la suite OpenOffice.org ; 

- Aux etudiants et a tous ceux qui souhaitent s'initier a I'API d'OpenOffice.org et a son langage de macros OOoBASIC. 
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